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

# 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

# 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

# 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:

# .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

# 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

# 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

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

# 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

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

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

Testing Configuration

# 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

   # Check if variables are set
   env | grep RUSTELO
   env | grep DATABASE_URL
   

2. Invalid Variable Format

   # Validate database URL format
   echo $DATABASE_URL | grep -E "^postgresql://"
   

3. Permission Issues

   # Check file permissions for certificates
   ls -la /etc/ssl/certs/yourapp.crt
   

Debug Environment Loading

# 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.