rweb_starterkit/docs/configuration.md

Configuration Guide

This guide provides detailed information on how to configure the Hostbasket application.

Table of Contents

1. Configuration Methods
2. Server Configuration
3. Templates Configuration
4. Authentication Configuration
5. OAuth Configuration
6. Database Configuration
7. Logging Configuration
8. Environment-Specific Configuration
9. Advanced Configuration

Configuration Methods

Hostbasket supports multiple configuration methods:

1. Environment Variables: Set configuration values using environment variables.
2. Configuration Files: Use TOML configuration files in the config directory.
3. Command-Line Arguments: Override specific settings using command-line arguments.

The configuration is loaded in the following order, with later methods overriding earlier ones:

1. Default values
2. Configuration files
3. Environment variables
4. Command-line arguments

Server Configuration

Environment Variables

export APP__SERVER__HOST=127.0.0.1
export APP__SERVER__PORT=9999
export APP__SERVER__WORKERS=4

Configuration File

[server]
host = "127.0.0.1"
port = 9999
workers = 4

Available Settings

Setting	Description	Default Value
host	The host address to bind to	127.0.0.1
port	The port to listen on	9999
workers	The number of worker threads	Number of CPU cores

Templates Configuration

Environment Variables

export APP__TEMPLATES__DIR=./src/views

Configuration File

[templates]
dir = "./src/views"

Available Settings

Setting	Description	Default Value
dir	The directory containing templates	./src/views

Authentication Configuration

Environment Variables

export JWT_SECRET=your_jwt_secret_key
export JWT_EXPIRATION_HOURS=24

Configuration File

[auth]
jwt_secret = "your_jwt_secret_key"
jwt_expiration_hours = 24

Available Settings

Setting	Description	Default Value
jwt_secret	The secret key used to sign JWT tokens	your_jwt_secret_key
jwt_expiration_hours	The number of hours before a JWT token expires	24

OAuth Configuration

Environment Variables

export GITEA_CLIENT_ID=your_client_id
export GITEA_CLIENT_SECRET=your_client_secret
export GITEA_INSTANCE_URL=https://your-gitea-instance.com

Configuration File

[oauth.gitea]
client_id = "your_client_id"
client_secret = "your_client_secret"
instance_url = "https://your-gitea-instance.com"

Available Settings

Setting	Description	Default Value
client_id	The OAuth client ID	None
client_secret	The OAuth client secret	None
instance_url	The URL of your Gitea instance	None

Database Configuration

Environment Variables

export APP__DATABASE__URL=postgres://user:password@localhost/hostbasket
export APP__DATABASE__POOL_SIZE=5

Configuration File

[database]
url = "postgres://user:password@localhost/hostbasket"
pool_size = 5

Available Settings

Setting	Description	Default Value
url	The database connection URL	None
pool_size	The size of the connection pool	5

Logging Configuration

Environment Variables

export RUST_LOG=info

Configuration File

[logging]
level = "info"

Available Settings

Setting	Description	Default Value
level	The log level (trace, debug, info, warn, error)	info

Environment-Specific Configuration

You can create environment-specific configuration files:

• config/default.toml: Default configuration for all environments
• config/development.toml: Configuration for development environment
• config/production.toml: Configuration for production environment
• config/test.toml: Configuration for test environment

To specify the environment:

export APP_ENV=production

Advanced Configuration

Custom Configuration

You can add custom configuration sections to the configuration file:

[custom]
setting1 = "value1"
setting2 = "value2"

To access these settings in your code:

let config = config::get_config();
let custom_config = config.get_table("custom").unwrap();
let setting1 = custom_config.get("setting1").unwrap().as_str().unwrap();

Configuration Validation

You can validate the configuration when loading it:

impl AppConfig {
    pub fn validate(&self) -> Result<(), String> {
        if self.server.port < 1024 && !cfg!(debug_assertions) {
            return Err("Port number should be >= 1024 in production".to_string());
        }
        
        Ok(())
    }
}

pub fn get_config() -> AppConfig {
    let config = AppConfig::new().expect("Failed to load configuration");
    
    if let Err(e) = config.validate() {
        panic!("Invalid configuration: {}", e);
    }
    
    config
}

Reloading Configuration

You can implement configuration reloading to update the configuration without restarting the application:

pub async fn reload_config() -> Result<AppConfig, ConfigError> {
    let config = AppConfig::new()?;
    
    // Update the global configuration
    let mut global_config = GLOBAL_CONFIG.write().await;
    *global_config = config.clone();
    
    Ok(config)
}

Secrets Management

For production environments, consider using a secrets management solution like HashiCorp Vault or AWS Secrets Manager instead of storing secrets in configuration files or environment variables.

You can implement a custom secrets provider:

pub async fn load_secrets() -> Result<(), Error> {
    // Load secrets from your secrets manager
    let jwt_secret = secrets_manager.get_secret("jwt_secret").await?;
    
    // Set the secrets as environment variables
    std::env::set_var("JWT_SECRET", jwt_secret);
    
    Ok(())
}

Call this function before loading the configuration:

#[actix_web::main]
async fn main() -> io::Result<()> {
    // Load secrets
    load_secrets().await.expect("Failed to load secrets");
    
    // Load configuration
    let config = config::get_config();
    
    // ...
}