Rustelo/book/getting-started/configuration.md

# Basic Configuration

<div align="center">
  <img src="../logos/rustelo_dev-logo-h.svg" alt="RUSTELO" width="300" />
</div>

Welcome to Rustelo's configuration system! This guide will help you get started with configuring your Rustelo application for different environments and use cases.

## Overview

Rustelo uses a powerful, modular configuration system that allows you to:

- Configure different settings for development, staging, and production
- Enable or disable features based on your needs
- Manage secrets securely through environment variables
- Build complete configurations from modular components

## Quick Start

### 1. Build Your First Configuration

The easiest way to get started is to build a development configuration:

```bash
# Navigate to your Rustelo project
cd your-rustelo-project

# Build development configuration
./config/scripts/build-config.sh dev
```

This creates a `config.toml` file with all the settings needed for development.

### 2. Environment Variables

Set up your basic environment variables:

```bash
# Create a .env file for development
cat > .env << EOF
DATABASE_URL=sqlite//:dev_database.db
SESSION_SECRET=your-development-session-secret
JWT_SECRET=your-development-jwt-secret
EOF
```

### 3. Start Your Application

With your configuration in place, you can start your application:

```bash
# Load environment variables and start
source .env
cargo run --bin server
```

## Configuration Structure

Rustelo's configuration is built from two main components:

### Base Configuration

Base configurations contain core settings that apply to all features:

- **Server settings**: Host, port, workers
- **Database settings**: Connection URL, pool size
- **Security settings**: CSRF protection, rate limiting
- **Session management**: Cookie settings, timeouts

### Feature Configuration

Feature configurations contain settings specific to individual features:

- **Authentication**: JWT settings, password policies, OAuth
- **Email**: SMTP configuration, templates, providers
- **Content**: Markdown processing, file uploads, search
- **Metrics**: Monitoring, alerts, dashboards
- **TLS**: SSL certificates, cipher suites, security headers

## Available Environments

Rustelo comes with three pre-configured environments:

### Development (`dev`)
- Optimized for developer experience
- Relaxed security settings
- Verbose logging
- SQLite database by default
- Hot reloading enabled

```bash
./config/scripts/build-config.sh dev
```

### Production (`prod`)
- Optimized for performance and security
- Strict security settings
- Minimal logging
- PostgreSQL database recommended
- Monitoring enabled

```bash
./config/scripts/build-config.sh prod config.prod.toml
```

### Example (`example`)
- Complete documentation of all options
- Best practice configurations
- Commented examples for learning

```bash
./config/scripts/build-config.sh example config.example.toml
```

## Essential Configuration Options

### Database Configuration

Choose your database backend:

```toml
[database]
# SQLite (great for development)
url = "sqlite://database.db"

# PostgreSQL (recommended for production)
url = "postgresql://user:password@localhost:5432/myapp"
```

### Server Configuration

Configure your web server:

```toml
[server]
host = "127.0.0.1"     # Development
# host = "0.0.0.0"     # Production
port = 3030
workers = 1            # Development
# workers = 4          # Production
```

### Feature Enablement

Enable the features you need:

```toml
[features]
auth = true           # User authentication
content = true        # Content management
email = false         # Email system (requires SMTP setup)
metrics = true        # Monitoring and metrics
tls = false          # SSL/TLS (enable for production)
```

## Environment Variables

Rustelo uses environment variables for sensitive configuration:

### Required Variables

For development:
```bash
DATABASE_URL=sqlite://dev_database.db           # Optional, has default
SESSION_SECRET=your-session-secret            # Required
```

For production:
```bash
DATABASE_URL=postgresql://user:pass@host/db   # Required
SESSION_SECRET=your-secure-session-secret     # Required (32+ chars)
JWT_SECRET=your-secure-jwt-secret             # Required (32+ chars)
DOMAIN=yourapp.com                            # Required for cookies
FRONTEND_URL=https://yourapp.com              # Required for CORS
```

### Optional Variables

Email configuration (if email feature enabled):
```bash
SMTP_HOST=smtp.gmail.com
SMTP_USERNAME=your-app@gmail.com
SMTP_PASSWORD=your-app-password
FROM_EMAIL=noreply@yourapp.com
```

TLS configuration (if TLS feature enabled):
```bash
TLS_CERT_FILE=/etc/ssl/certs/yourapp.crt
TLS_KEY_FILE=/etc/ssl/private/yourapp.key
```

## Feature Configuration Examples

### Authentication Setup

Enable authentication with basic settings:

```toml
[features]
auth = true

[auth.jwt]
secret = "${JWT_SECRET}"
expiration = 3600      # 1 hour

[auth.password]
min_length = 8
require_numbers = true
```

### Email Setup

Configure email for notifications:

```toml
[features]
email = true

[email]
provider = "smtp"
from_email = "${FROM_EMAIL}"

[email.smtp]
host = "${SMTP_HOST}"
port = 587
username = "${SMTP_USERNAME}"
password = "${SMTP_PASSWORD}"
use_tls = true
```

### Content Management

Enable content features:

```toml
[features]
content = true

[content]
enabled = true
max_file_size = 10485760    # 10MB
allowed_file_types = ["jpg", "png", "pdf", "md"]

[content.markdown]
enabled = true
syntax_highlighting = true
```

## Configuration Management

### List Available Features

See what features are available:

```bash
./config/scripts/debug-manage.sh list-features
```

### Check Configuration Status

Review your current configuration:

```bash
./config/scripts/debug-manage.sh status
```

### Compare Environments

Compare settings between environments:

```bash
# Build both configurations first
./config/scripts/build-config.sh dev config.dev.toml
./config/scripts/build-config.sh prod config.prod.toml

# Compare them
diff config.dev.toml config.prod.toml
```

### Backup Configurations

Backup your current configuration:

```bash
cp config.toml config.backup.toml
```

## Common Configuration Patterns

### Development Setup

For local development:

```bash
# Set environment
export RUSTELO_ENV=development

# Simple database
export DATABASE_URL=sqlite://dev_database.db

# Basic auth secrets
export SESSION_SECRET=dev-session-secret
export JWT_SECRET=dev-jwt-secret

# Build config
./config/scripts/build-config.sh dev
```

### Production Setup

For production deployment:

```bash
# Set environment
export RUSTELO_ENV=production

# Production database
export DATABASE_URL=postgresql://user:password@db:5432/app

# Secure secrets (use a secret manager in real deployments)
export SESSION_SECRET=$(openssl rand -base64 32)
export JWT_SECRET=$(openssl rand -base64 32)

# Domain configuration
export DOMAIN=yourapp.com
export FRONTEND_URL=https://yourapp.com

# Build config
./config/scripts/build-config.sh prod config.prod.toml
```

### Docker Setup

For containerized deployment:

```dockerfile
FROM rust:1.70 as builder
WORKDIR /app
COPY . .
RUN ./config/scripts/build-config.sh prod config.prod.toml
RUN cargo build --release

FROM debian:bookworm-slim
COPY --from=builder /app/target/release/server /usr/local/bin/
COPY --from=builder /app/config.prod.toml /etc/rustelo/config.toml

ENV RUSTELO_CONFIG_FILE=/etc/rustelo/config.toml
EXPOSE 3030
CMD ["server"]
```

## Troubleshooting

### Configuration Build Fails

If configuration building fails:

1. Check that all required files exist:
   ```bash
   ls -la config/base/
   ls -la config/features/
   ```

2. Validate individual files:
   ```bash
   # Check base configuration
   cat config/base/dev.toml

   # Check feature configurations
   cat config/features/auth/dev.toml
   ```

3. Check for syntax errors:
   ```bash
   # Install TOML validator (optional)
   cargo install toml-cli

   # Validate syntax
   toml get config/base/dev.toml
   ```

### Missing Environment Variables

If you get errors about missing environment variables:

1. Check required variables are set:
   ```bash
   echo $DATABASE_URL
   echo $SESSION_SECRET
   echo $JWT_SECRET
   ```

2. Create a .env file:
   ```bash
   cat > .env << EOF
   DATABASE_URL=sqlite:dev_database.db
   SESSION_SECRET=your-session-secret
   JWT_SECRET=your-jwt-secret
   EOF

   # Load environment
   source .env
   ```

### Application Won't Start

If the application fails to start:

1. Check configuration file exists:
   ```bash
   ls -la config.toml
   ```

2. Validate configuration:
   ```bash
   ./config/scripts/debug-manage.sh status
   ```

3. Check logs for specific errors:
   ```bash
   cargo run --bin server 2>&1 | head -20
   ```

## Next Steps

Now that you have basic configuration working:

1. **Explore Features**: Learn about [Features Configuration](../configuration/features.md)
2. **Security Setup**: Review [Security Settings](../configuration/security.md)
3. **Environment Variables**: Deep dive into [Environment Variables](../configuration/environment.md)
4. **Production Deployment**: Check out [Production Setup](../deployment/production.md)
5. **Performance Tuning**: Optimize with [Performance Configuration](../configuration/performance.md)

## Getting Help

If you need assistance with configuration:

- Check the [Troubleshooting Guide](../troubleshooting/common.md)
- Review the [Configuration Files Guide](../configuration/files.md)
- Look at example configurations in `config/features/*/example.toml`
- Ask questions in the community forums

The configuration system is designed to be flexible and powerful while remaining approachable for new users. Start simple and add complexity as your needs grow!