Rustelo/book/configuration/environment.md

# Environment Variables

Rustelo uses environment variables to configure sensitive settings, deployment-specific values, and runtime parameters. This approach ensures that secrets are kept separate from the codebase while allowing flexible configuration across different environments.

## Overview

Environment variables in Rustelo are used for:

- **Sensitive Information**: Database credentials, API keys, secrets
- **Environment-Specific Settings**: URLs, domains, feature flags
- **Runtime Configuration**: Debug modes, logging levels, performance tuning
- **Third-Party Integration**: External service configuration

## Variable Categories

### Core System Variables

#### `RUSTELO_ENV`
- **Description**: Application environment
- **Values**: `development`, `production`, `staging`, `test`
- **Default**: `development`
- **Example**: `RUSTELO_ENV=production`

#### `RUSTELO_CONFIG_FILE`
- **Description**: Path to configuration file
- **Default**: `config.toml`
- **Example**: `RUSTELO_CONFIG_FILE=/etc/rustelo/config.prod.toml`

#### `RUSTELO_LOG_LEVEL`
- **Description**: Global log level override
- **Values**: `error`, `warn`, `info`, `debug`, `trace`
- **Default**: From config file
- **Example**: `RUSTELO_LOG_LEVEL=info`

### Database Configuration

#### `DATABASE_URL`
- **Description**: Database connection string
- **Required**: Yes (production)
- **Format**: `postgresql://user:password@host:port/database`
- **Example**: `DATABASE_URL=postgresql://rustelo:password@localhost:5432/rustelo_prod`

#### `DATABASE_MAX_CONNECTIONS`
- **Description**: Maximum database connections
- **Default**: From config file
- **Example**: `DATABASE_MAX_CONNECTIONS=20`

#### `DATABASE_SSL_MODE`
- **Description**: Database SSL mode
- **Values**: `disable`, `allow`, `prefer`, `require`
- **Default**: `prefer`
- **Example**: `DATABASE_SSL_MODE=require`

### Authentication & Security

#### `SESSION_SECRET`
- **Description**: Session encryption secret
- **Required**: Yes
- **Min Length**: 32 characters
- **Example**: `SESSION_SECRET=your-very-long-and-secure-session-secret-here`

#### `JWT_SECRET`
- **Description**: JWT signing secret
- **Required**: Yes (if JWT enabled)
- **Min Length**: 32 characters
- **Example**: `JWT_SECRET=your-jwt-signing-secret-here`

#### `ENCRYPTION_KEY`
- **Description**: Application-level encryption key
- **Required**: Yes (if encryption enabled)
- **Length**: 32 bytes (base64 encoded)
- **Example**: `ENCRYPTION_KEY=your-base64-encoded-encryption-key`

#### `CSRF_SECRET`
- **Description**: CSRF protection secret
- **Required**: No (auto-generated if not provided)
- **Example**: `CSRF_SECRET=your-csrf-secret-here`

### Email Configuration

#### `SMTP_HOST`
- **Description**: SMTP server hostname
- **Required**: Yes (if email enabled)
- **Example**: `SMTP_HOST=smtp.gmail.com`

#### `SMTP_PORT`
- **Description**: SMTP server port
- **Default**: `587`
- **Example**: `SMTP_PORT=587`

#### `SMTP_USERNAME`
- **Description**: SMTP authentication username
- **Required**: Yes (if SMTP auth enabled)
- **Example**: `SMTP_USERNAME=your-app@gmail.com`

#### `SMTP_PASSWORD`
- **Description**: SMTP authentication password
- **Required**: Yes (if SMTP auth enabled)
- **Example**: `SMTP_PASSWORD=your-app-password`

#### `FROM_EMAIL`
- **Description**: Default sender email address
- **Required**: Yes (if email enabled)
- **Example**: `FROM_EMAIL=noreply@yourapp.com`

#### `FROM_NAME`
- **Description**: Default sender name
- **Default**: Application name
- **Example**: `FROM_NAME=Your App Name`

### Web Server Configuration

#### `RUSTELO_HOST`
- **Description**: Server bind address
- **Default**: `127.0.0.1` (dev), `0.0.0.0` (prod)
- **Example**: `RUSTELO_HOST=0.0.0.0`

#### `RUSTELO_PORT`
- **Description**: Server port
- **Default**: `3030`
- **Example**: `RUSTELO_PORT=8080`

#### `RUSTELO_WORKERS`
- **Description**: Number of worker threads
- **Default**: CPU core count
- **Example**: `RUSTELO_WORKERS=4`

#### `DOMAIN`
- **Description**: Application domain for cookies and CORS
- **Required**: Yes (production)
- **Example**: `DOMAIN=yourapp.com`

#### `FRONTEND_URL`
- **Description**: Frontend application URL
- **Required**: Yes (if separate frontend)
- **Example**: `FRONTEND_URL=https://app.yourapp.com`

### Redis Configuration

#### `REDIS_URL`
- **Description**: Redis connection string
- **Required**: Yes (if Redis enabled)
- **Example**: `REDIS_URL=redis://localhost:6379`

#### `REDIS_PASSWORD`
- **Description**: Redis authentication password
- **Required**: No (if Redis auth disabled)
- **Example**: `REDIS_PASSWORD=your-redis-password`

#### `REDIS_DATABASE`
- **Description**: Redis database number
- **Default**: `0`
- **Example**: `REDIS_DATABASE=1`

### SSL/TLS Configuration

#### `TLS_CERT_FILE`
- **Description**: Path to TLS certificate file
- **Required**: Yes (if HTTPS enabled)
- **Example**: `TLS_CERT_FILE=/etc/ssl/certs/yourapp.crt`

#### `TLS_KEY_FILE`
- **Description**: Path to TLS private key file
- **Required**: Yes (if HTTPS enabled)
- **Example**: `TLS_KEY_FILE=/etc/ssl/private/yourapp.key`

#### `TLS_CA_FILE`
- **Description**: Path to TLS CA certificate file
- **Required**: No
- **Example**: `TLS_CA_FILE=/etc/ssl/certs/ca-certificates.crt`

### External Services

#### `OAUTH_GOOGLE_CLIENT_ID`
- **Description**: Google OAuth client ID
- **Required**: Yes (if Google OAuth enabled)
- **Example**: `OAUTH_GOOGLE_CLIENT_ID=your-google-client-id`

#### `OAUTH_GOOGLE_CLIENT_SECRET`
- **Description**: Google OAuth client secret
- **Required**: Yes (if Google OAuth enabled)
- **Example**: `OAUTH_GOOGLE_CLIENT_SECRET=your-google-client-secret`

#### `OAUTH_GITHUB_CLIENT_ID`
- **Description**: GitHub OAuth client ID
- **Required**: Yes (if GitHub OAuth enabled)
- **Example**: `OAUTH_GITHUB_CLIENT_ID=your-github-client-id`

#### `OAUTH_GITHUB_CLIENT_SECRET`
- **Description**: GitHub OAuth client secret
- **Required**: Yes (if GitHub OAuth enabled)
- **Example**: `OAUTH_GITHUB_CLIENT_SECRET=your-github-client-secret`

### Monitoring & Observability

#### `PROMETHEUS_ENDPOINT`
- **Description**: Prometheus metrics endpoint
- **Default**: `/metrics`
- **Example**: `PROMETHEUS_ENDPOINT=/prometheus`

#### `JAEGER_ENDPOINT`
- **Description**: Jaeger tracing endpoint
- **Required**: No
- **Example**: `JAEGER_ENDPOINT=http://localhost:14268/api/traces`

#### `SENTRY_DSN`
- **Description**: Sentry error reporting DSN
- **Required**: No
- **Example**: `SENTRY_DSN=https://your-sentry-dsn@sentry.io/project-id`

### Development & Debug

#### `RUST_LOG`
- **Description**: Rust logging configuration
- **Default**: `info`
- **Example**: `RUST_LOG=rustelo=debug,sqlx=info`

#### `RUST_BACKTRACE`
- **Description**: Enable Rust backtraces
- **Values**: `0`, `1`, `full`
- **Default**: `0`
- **Example**: `RUST_BACKTRACE=1`

#### `RUSTELO_DEBUG`
- **Description**: Enable debug mode
- **Values**: `true`, `false`
- **Default**: `false`
- **Example**: `RUSTELO_DEBUG=true`

#### `RUSTELO_MOCK_EXTERNAL`
- **Description**: Mock external services
- **Values**: `true`, `false`
- **Default**: `false`
- **Example**: `RUSTELO_MOCK_EXTERNAL=true`

## Environment-Specific Configuration

### Development Environment

```bash
# Core settings
RUSTELO_ENV=development
RUSTELO_LOG_LEVEL=debug
RUSTELO_DEBUG=true

# Database
DATABASE_URL=sqlite//:dev_database.db

# Authentication
SESSION_SECRET=dev-session-secret-change-in-production
JWT_SECRET=dev-jwt-secret-change-in-production

# Email (console output)
SMTP_HOST=localhost
SMTP_PORT=1025
FROM_EMAIL=dev@localhost

# Features
RUSTELO_MOCK_EXTERNAL=true
```

### Production Environment

```bash
# Core settings
RUSTELO_ENV=production
RUSTELO_LOG_LEVEL=info
RUSTELO_DEBUG=false

# Server
RUSTELO_HOST=0.0.0.0
RUSTELO_PORT=443
DOMAIN=yourapp.com
FRONTEND_URL=https://yourapp.com

# Database
DATABASE_URL=postgresql://rustelo:password@db-server:5432/rustelo_prod
DATABASE_MAX_CONNECTIONS=20
DATABASE_SSL_MODE=require

# Authentication
SESSION_SECRET=your-production-session-secret-64-chars-long
JWT_SECRET=your-production-jwt-secret-64-chars-long
ENCRYPTION_KEY=your-base64-encoded-encryption-key

# Email
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=your-app@gmail.com
SMTP_PASSWORD=your-app-password
FROM_EMAIL=noreply@yourapp.com
FROM_NAME=Your App

# Redis
REDIS_URL=redis://redis-server:6379
REDIS_PASSWORD=your-redis-password

# TLS
TLS_CERT_FILE=/etc/ssl/certs/yourapp.crt
TLS_KEY_FILE=/etc/ssl/private/yourapp.key

# OAuth
OAUTH_GOOGLE_CLIENT_ID=your-google-client-id
OAUTH_GOOGLE_CLIENT_SECRET=your-google-client-secret

# Monitoring
SENTRY_DSN=https://your-sentry-dsn@sentry.io/project-id
```

### Staging Environment

```bash
# Core settings
RUSTELO_ENV=staging
RUSTELO_LOG_LEVEL=info
RUSTELO_DEBUG=true

# Server
RUSTELO_HOST=0.0.0.0
RUSTELO_PORT=443
DOMAIN=staging.yourapp.com
FRONTEND_URL=https://staging.yourapp.com

# Database
DATABASE_URL=postgresql://rustelo:password@staging-db:5432/rustelo_staging
DATABASE_MAX_CONNECTIONS=10
DATABASE_SSL_MODE=prefer

# Authentication (use staging secrets)
SESSION_SECRET=staging-session-secret-64-chars-long
JWT_SECRET=staging-jwt-secret-64-chars-long

# Email (test configuration)
SMTP_HOST=smtp.mailtrap.io
SMTP_PORT=2525
SMTP_USERNAME=your-mailtrap-username
SMTP_PASSWORD=your-mailtrap-password
FROM_EMAIL=staging@yourapp.com
```

## Environment File Management

### `.env` Files

Create environment-specific `.env` files:

```bash
# .env.development
RUSTELO_ENV=development
DATABASE_URL=sqlite:dev_database.db
SESSION_SECRET=dev-session-secret
JWT_SECRET=dev-jwt-secret

# .env.production
RUSTELO_ENV=production
DATABASE_URL=postgresql://user:pass@host:5432/db
SESSION_SECRET=prod-session-secret
JWT_SECRET=prod-jwt-secret

# .env.staging
RUSTELO_ENV=staging
DATABASE_URL=postgresql://user:pass@staging-host:5432/db
SESSION_SECRET=staging-session-secret
JWT_SECRET=staging-jwt-secret
```

### Loading Environment Files

```bash
# Load development environment
source .env.development

# Load production environment
source .env.production

# Load with dotenv (if using dotenv tool)
dotenv -f .env.production -- ./rustelo-server
```

## Docker Configuration

### Docker Compose

```yaml
# docker-compose.yml
version: '3.8'

services:
  app:
    build: .
    environment:
      - RUSTELO_ENV=production
      - DATABASE_URL=postgresql://rustelo:password@db:5432/rustelo
      - SESSION_SECRET=your-session-secret
      - JWT_SECRET=your-jwt-secret
      - REDIS_URL=redis://redis:6379
    env_file:
      - .env.production
    depends_on:
      - db
      - redis

  db:
    image: postgres:15
    environment:
      - POSTGRES_DB=rustelo
      - POSTGRES_USER=rustelo
      - POSTGRES_PASSWORD=password

  redis:
    image: redis:7-alpine
    command: redis-server --requirepass your-redis-password
```

### Dockerfile

```dockerfile
FROM rust:1.70 as builder

WORKDIR /app
COPY . .
RUN cargo build --release

FROM debian:bookworm-slim

# Install runtime dependencies
RUN apt-get update && apt-get install -y \
    ca-certificates \
    && rm -rf /var/lib/apt/lists/*

COPY --from=builder /app/target/release/rustelo-server /usr/local/bin/
COPY --from=builder /app/config.prod.toml /etc/rustelo/config.toml

# Environment variables can be set here or passed at runtime
ENV RUSTELO_ENV=production
ENV RUSTELO_CONFIG_FILE=/etc/rustelo/config.toml

EXPOSE 3030

CMD ["rustelo-server"]
```

## Security Best Practices

### Secret Management

1. **Use Strong Secrets**
   - Minimum 32 characters for session secrets
   - Use cryptographically secure random generators
   - Rotate secrets regularly

2. **Environment Separation**
   - Never use production secrets in development
   - Use different secrets for each environment
   - Store secrets in secure vaults (HashiCorp Vault, AWS Secrets Manager)

3. **Access Control**
   - Limit access to environment variables
   - Use least privilege principle
   - Audit secret access

### Example Secret Generation

```bash
# Generate secure session secret
openssl rand -base64 64

# Generate JWT secret
openssl rand -base64 64

# Generate encryption key
openssl rand -base64 32

# Generate CSRF secret
openssl rand -base64 32
```

## Validation and Testing

### Variable Validation

```bash
# Check required variables
./scripts/check-env.sh production

# Validate configuration
./config/scripts/build-config.sh prod --validate-only
```

### Testing Configuration

```bash
# Test with environment variables
RUSTELO_ENV=test DATABASE_URL=sqlite::memory: cargo test

# Test configuration loading
./rustelo-server --check-config
```

## Troubleshooting

### Common Issues

1. **Missing Environment Variables**
   ```bash
   # Check if variables are set
   env | grep RUSTELO
   env | grep DATABASE_URL
   ```

2. **Invalid Variable Format**
   ```bash
   # Validate database URL format
   echo $DATABASE_URL | grep -E "^postgresql://"
   ```

3. **Permission Issues**
   ```bash
   # Check file permissions for certificates
   ls -la /etc/ssl/certs/yourapp.crt
   ```

### Debug Environment Loading

```bash
# Enable debug logging
RUST_LOG=rustelo=debug ./rustelo-server

# Show loaded configuration
./rustelo-server --show-config
```

## Migration Guide

When updating environment variables:

1. **Add new variables** to all environments
2. **Update documentation** with new requirements
3. **Provide default values** where possible
4. **Test thoroughly** in staging before production
5. **Update deployment scripts** and Docker configurations

For detailed migration instructions, see the [Environment Migration Guide](../reference/env-migration.md).