feat: Add basic project structure and configuration

- Add `.env.template` file for environment variable configuration. - Add `.gitignore` file to ignore generated files and IDE artifacts. - Add `Cargo.toml` file specifying project dependencies. - Add basic project documentation in `README.md` and configuration guide in `docs/configuration.md`. - Add Gitea authentication guide in `docs/gitea-auth.md`. - Add installation guide in `docs/installation.md`. - Add MVC architecture guide in `docs/mvc.md`. - Add views guide in `docs/views.md`.
2025-05-07 14:03:08 +03:00
parent 84d357f0c5
commit 645a387528
26 changed files with 2646 additions and 1 deletions
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -0,0 +1,284 @@
+# 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();
+    
+    // ...
+}
+```