Rustelo/templates/shared/docs/CONFIG_WIZARD.md

Configuration Wizard Documentation

The Rustelo Configuration Wizard is an interactive tool that helps you set up your application by generating a customized config.toml file and updating the Cargo.toml features based on your specific needs.

Overview

The wizard provides two implementations:

1. Simple Wizard (simple_config_wizard.rs) - Pure Rust implementation
2. Advanced Wizard (config_wizard.rs) - Uses Rhai scripting engine for more flexibility

Features

Available Features

Feature	Description	Dependencies
auth	Authentication and authorization system	crypto
tls	TLS/SSL support for secure connections	-
rbac	Role-based access control	auth
crypto	Cryptographic utilities and encryption	-
content-db	Content management and database features	-
email	Email sending capabilities	-
metrics	Prometheus metrics collection	-
examples	Include example code and documentation	-
production	Production-ready configuration	All features

Configuration Sections

The wizard will configure the following sections based on your selections:

• Server Configuration: Host, port, environment, workers
• Database Configuration: Connection URL, pool settings, logging
• Authentication: JWT settings, session management, login attempts
• OAuth Providers: Google, GitHub, Microsoft integration
• Email Settings: SMTP configuration, from addresses
• Security: CSRF protection, rate limiting, BCrypt cost
• SSL/TLS: HTTPS enforcement, certificate paths
• Monitoring: Metrics collection, Prometheus integration
• Caching: Cache type, TTL settings

Usage

Quick Start

Run the wizard using the provided script:

./scripts/run_wizard.sh

Manual Execution

Simple Wizard

cd server
cargo run --bin simple_config_wizard

Advanced Wizard (requires Rhai)

cd server
cargo run --bin config_wizard

Example Session

=== Rustelo Configuration Wizard ===
This wizard will help you configure your Rustelo application.

--- Feature Selection ---
Select the features you want to enable:

Enable auth? (Authentication and authorization system) (y/n): y
Enable tls? (TLS/SSL support for secure connections) (y/n): y
Enable email? (Email sending capabilities) (y/n): y
Enable metrics? (Prometheus metrics collection) (y/n): n

--- Server Configuration ---
Server host [127.0.0.1]: 
Server port [3030]: 8080
Environment (dev/prod/test) [dev]: prod
Number of workers [4]: 8

--- Database Configuration ---
Database URL [sqlite:rustelo.db]: postgresql://user:pass@localhost/rustelo
Max database connections [10]: 20
Enable database query logging (y/n): y

--- Authentication Configuration ---
JWT secret (leave empty for auto-generation): 
Session timeout (minutes) [60]: 120
Max login attempts [5]: 3
Require email verification (y/n): y

Enable OAuth providers? (y/n): y
Enable Google OAuth? (y/n): y
Google OAuth Client ID: your-google-client-id
Google OAuth Client Secret: your-google-client-secret
Google OAuth Redirect URI [http://localhost:3030/auth/google/callback]: https://yourdomain.com/auth/google/callback

--- Email Configuration ---
SMTP host [localhost]: smtp.gmail.com
SMTP port [587]: 
SMTP username: your-email@gmail.com
SMTP password: your-app-password
From email address [noreply@localhost]: noreply@yourdomain.com
From name [Rustelo App]: Your App Name

--- Security Configuration ---
Enable CSRF protection (y/n): y
Rate limit requests per minute [100]: 200
BCrypt cost (4-31) [12]: 

--- SSL/TLS Configuration ---
Force HTTPS (y/n): y
SSL certificate path: /path/to/cert.pem
SSL private key path: /path/to/key.pem

Generate configuration files? (y/n): y

Generated Files

config.toml

The wizard generates a complete config.toml file with all the sections you configured:

# Rustelo Configuration File
# Generated by Configuration Wizard

root_path = "."

[features]
auth = true
tls = true
crypto = true
email = true

[server]
protocol = "http"
host = "127.0.0.1"
port = 8080
environment = "prod"
workers = 8

[database]
url = "postgresql://user:pass@localhost/rustelo"
max_connections = 20
enable_logging = true

[auth.jwt]
secret = "your-generated-secret"
expiration = 7200

[oauth]
enabled = true

[oauth.google]
client_id = "your-google-client-id"
client_secret = "your-google-client-secret"
redirect_uri = "https://yourdomain.com/auth/google/callback"

# ... more sections

Cargo.toml Updates

The wizard automatically updates your server/Cargo.toml default features:

[features]
default = ["auth", "tls", "crypto", "email"]

Advanced Usage

Using Rhai Scripts

The advanced wizard uses Rhai scripting for more flexibility. You can modify the scripts/config_wizard.rhai file to:

• Add custom configuration sections
• Implement complex validation logic
• Create conditional configurations
• Add custom feature dependencies

Custom Feature Dependencies

The wizard automatically resolves feature dependencies. For example:

• Selecting rbac automatically enables auth
• Selecting production enables all features
• Selecting auth automatically enables crypto

Environment-Specific Configurations

You can run the wizard multiple times to generate different configurations:

# Generate development config
./scripts/run_wizard.sh
mv config.toml config.dev.toml

# Generate production config
./scripts/run_wizard.sh
mv config.toml config.prod.toml

Security Considerations

Sensitive Data

The wizard will prompt for sensitive information like:

• Database passwords
• OAuth client secrets
• JWT secrets
• SMTP passwords
• SSL certificate paths

Important: Never commit these secrets to version control. Use environment variables or secret management systems in production.

Recommended Setup

1. Generate configuration with placeholder values
2. Replace sensitive values with environment variables:

[database]
url = "${DATABASE_URL}"

[oauth.google]
client_secret = "${GOOGLE_CLIENT_SECRET}"

3. Set environment variables:

export DATABASE_URL="postgresql://user:pass@localhost/rustelo"
export GOOGLE_CLIENT_SECRET="your-actual-secret"

Troubleshooting

Common Issues

"Cargo.toml not found"

• Ensure you're running the wizard from the project root directory
• Check that the server/Cargo.toml file exists

"Feature build errors"

• Some features may require additional system dependencies
• Run cargo check to verify feature compatibility
• Review the generated Cargo.toml for conflicts

"Configuration validation failed"

• Check that all required fields are properly filled
• Verify database connection strings
• Ensure OAuth redirect URIs match your domain

Debug Mode

Run the wizard with debug output:

RUST_LOG=debug cargo run --bin simple_config_wizard

Backup and Recovery

The wizard automatically creates backups:

• config.toml.bak - Backup of previous config
• server/Cargo.toml.bak - Backup of previous Cargo.toml

To restore from backup:

cp config.toml.bak config.toml
cp server/Cargo.toml.bak server/Cargo.toml

Integration with CI/CD

Automated Configuration

For CI/CD pipelines, you can run the wizard non-interactively:

# Use environment variables for configuration
export RUSTELO_FEATURES="auth,tls,metrics"
export RUSTELO_ENVIRONMENT="prod"
export RUSTELO_DATABASE_URL="postgresql://..."

# Run automated configuration
./scripts/run_wizard.sh --non-interactive

Docker Integration

Include the wizard in your Docker build:

FROM rust:1.75

COPY . /app
WORKDIR /app

# Run configuration wizard
RUN ./scripts/run_wizard.sh --non-interactive

# Build application
RUN cargo build --release

Contributing

Adding New Features

To add a new feature to the wizard:

1. Update the FeatureInfo struct in the wizard code
2. Add the feature to the features HashMap
3. Add configuration logic for the new feature
4. Update the TOML generation code
5. Add the feature to server/Cargo.toml
6. Update this documentation

Extending Configuration Sections

To add new configuration sections:

1. Create a new struct for the configuration
2. Add the struct to WizardConfig
3. Implement the interactive prompts
4. Add TOML serialization logic
5. Update the documentation

Examples

Minimal Configuration

For a simple development setup:

# Select only: auth, examples
# Use defaults for most settings
# SQLite database
# No OAuth, no email

Production Configuration

For a production deployment:

# Select: auth, tls, crypto, email, metrics
# PostgreSQL database
# OAuth providers enabled
# HTTPS enforced
# Email configured
# Monitoring enabled

API-Only Configuration

For a headless API service:

# Select: auth, crypto, metrics
# No email, no OAuth
# Focus on security and monitoring

References

• Rhai Scripting Language
• TOML Configuration Format
• Cargo Features Documentation
• Rustelo Template Documentation