Rustelo/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:

```bash
./scripts/run_wizard.sh
```

### Manual Execution

#### Simple Wizard
```bash
cd server
cargo run --bin simple_config_wizard
```

#### Advanced Wizard (requires Rhai)
```bash
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:

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

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

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

```toml
[database]
url = "${DATABASE_URL}"

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

3. Set environment variables:

```bash
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:

```bash
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:

```bash
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:

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

```dockerfile
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:

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

### Production Configuration

For a production deployment:

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

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

## References

- [Rhai Scripting Language](https://rhai.rs/)
- [TOML Configuration Format](https://toml.io/)
- [Cargo Features Documentation](https://doc.rust-lang.org/cargo/reference/features.html)
- [Rustelo Template Documentation](../README.md)