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](#configuration-methods)
2. [Server Configuration](#server-configuration)
3. [Templates Configuration](#templates-configuration)
4. [Authentication Configuration](#authentication-configuration)
5. [OAuth Configuration](#oauth-configuration)
6. [Database Configuration](#database-configuration)
7. [Logging Configuration](#logging-configuration)
8. [Environment-Specific Configuration](#environment-specific-configuration)
9. [Advanced Configuration](#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

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

### Configuration File

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

```bash
export APP__TEMPLATES__DIR=./src/views
```

### Configuration File

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

### Available Settings

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

## Authentication Configuration

### Environment Variables

```bash
export JWT_SECRET=your_jwt_secret_key
export JWT_EXPIRATION_HOURS=24
```

### Configuration File

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

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

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

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

### Configuration File

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

```bash
export RUST_LOG=info
```

### Configuration File

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

```bash
export APP_ENV=production
```

## Advanced Configuration

### Custom Configuration

You can add custom configuration sections to the configuration file:

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

To access these settings in your code:

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

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

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

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

```rust
#[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();
    
    // ...
}
```