Rustelo/book/getting-started/configuration.md

Basic Configuration

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:

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

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

# 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

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

Production (prod)

• Optimized for performance and security
• Strict security settings
• Minimal logging
• PostgreSQL database recommended
• Monitoring enabled

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

Example (example)

• Complete documentation of all options
• Best practice configurations
• Commented examples for learning

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

Essential Configuration Options

Database Configuration

Choose your database backend:

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

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

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

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

For production:

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

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

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:

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

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

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

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

Check Configuration Status

Review your current configuration:

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

Compare Environments

Compare settings between environments:

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

cp config.toml config.backup.toml

Common Configuration Patterns

Development Setup

For local development:

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

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

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:

   ls -la config/base/
   ls -la config/features/
   

2. Validate individual files:

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

3. Check for syntax errors:

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

   echo $DATABASE_URL
   echo $SESSION_SECRET
   echo $JWT_SECRET
   

2. Create a .env file:

   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:

   ls -la config.toml
   

2. Validate configuration:

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

3. Check logs for specific errors:

   cargo run --bin server 2>&1 | head -20
   

Next Steps

Now that you have basic configuration working:

1. Explore Features: Learn about Features Configuration
2. Security Setup: Review Security Settings
3. Environment Variables: Deep dive into Environment Variables
4. Production Deployment: Check out Production Setup
5. Performance Tuning: Optimize with Performance Configuration

Getting Help

If you need assistance with configuration:

• Check the Troubleshooting Guide
• Review the Configuration Files Guide
• 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!