re-uploading work

2026-02-04 17:46:30 -06:00
commit 3b14c65998
1388 changed files with 381262 additions and 0 deletions
--- a/docs/configuration/config-troubleshooting.md
+++ b/docs/configuration/config-troubleshooting.md
@@ -0,0 +1,554 @@
+# Configuration Troubleshooting Guide
+
+This guide helps you troubleshoot common configuration issues with Attune.
+
+## Quick Diagnostics
+
+### Check Configuration is Valid
+
+```bash
+# Test configuration loading
+cargo run --bin attune-api -- --help
+
+# Enable debug logging to see config details
+ATTUNE__LOG__LEVEL=debug cargo run --bin attune-api
+```
+
+### Verify Configuration Files Exist
+
+```bash
+# Check for config files
+ls -la config*.yaml
+
+# View current configuration
+cat config.yaml
+```
+
+### Test Environment Variables
+
+```bash
+# List all Attune environment variables
+env | grep ATTUNE
+
+# Test a specific variable
+echo $ATTUNE__DATABASE__URL
+```
+
+## Common Issues
+
+### 1. Encryption Key Must Be At Least 32 Characters
+
+**Error:**
+```
+Error: Validation error: Encryption key must be at least 32 characters
+```
+
+**Cause:** The `encryption_key` in your configuration is less than 32 characters.
+
+**Solution:**
+
+Generate a proper encryption key:
+```bash
+# Generate a 32-byte key (base64 encoded = ~44 characters)
+openssl rand -base64 32
+
+# Example output:
+# R3mHJ8qP5xK2nB9vW7tY4uZ1aE6cF0dG8hI2jK4lM5n=
+```
+
+Update your configuration:
+```yaml
+security:
+  encryption_key: R3mHJ8qP5xK2nB9vW7tY4uZ1aE6cF0dG8hI2jK4lM5n=
+```
+
+Or use an environment variable:
+```bash
+export ATTUNE__SECURITY__ENCRYPTION_KEY=$(openssl rand -base64 32)
+```
+
+**Note:** The key must be **at least 32 characters** after base64 decoding. A 32-byte random value base64-encoded is typically 44 characters.
+
+### 2. JWT Secret Required
+
+**Error:**
+```
+Error: Validation error: JWT secret is required when authentication is enabled
+```
+
+**Cause:** Authentication is enabled but no JWT secret is configured.
+
+**Solution Option 1 - Provide a JWT secret:**
+```yaml
+security:
+  jwt_secret: your-secret-here
+  enable_auth: true
+```
+
+Generate a secure secret:
+```bash
+openssl rand -base64 64
+```
+
+**Solution Option 2 - Disable authentication (dev only):**
+```yaml
+security:
+  enable_auth: false
+```
+
+### 3. Configuration File Not Found
+
+**Error:**
+```
+Error: Configuration error: ...
+```
+
+**Cause:** The application can't find `config.yaml`.
+
+**Solution:**
+
+Check if the file exists:
+```bash
+ls -la config.yaml
+```
+
+If missing, create it from the example:
+```bash
+cp config.example.yaml config.yaml
+nano config.yaml
+```
+
+Or specify a custom path:
+```bash
+export ATTUNE_CONFIG=/path/to/config.yaml
+cargo run --bin attune-api
+```
+
+### 4. Database Connection Failed
+
+**Error:**
+```
+Error: Database error: connection refused
+Error: Database error: password authentication failed
+```
+
+**Cause:** Cannot connect to PostgreSQL database.
+
+**Solution:**
+
+1. **Verify PostgreSQL is running:**
+   ```bash
+   pg_isready -h localhost -p 5432
+   ```
+
+2. **Check connection string:**
+   ```yaml
+   database:
+     url: postgresql://username:password@host:port/database
+   ```
+
+3. **Test connection manually:**
+   ```bash
+   psql postgresql://postgres:postgres@localhost:5432/attune
+   ```
+
+4. **Verify database exists:**
+   ```bash
+   psql -U postgres -c "SELECT datname FROM pg_database WHERE datname='attune';"
+   ```
+
+5. **Create database if needed:**
+   ```bash
+   createdb -U postgres attune
+   ```
+
+### 5. Invalid Log Level
+
+**Error:**
+```
+Error: Invalid log level: TRACE. Must be one of: ["trace", "debug", "info", "warn", "error"]
+```
+
+**Cause:** Log level must be lowercase.
+
+**Solution:**
+```yaml
+log:
+  level: debug  # Use lowercase
+```
+
+Not:
+```yaml
+log:
+  level: DEBUG  # Wrong - uppercase not allowed
+```
+
+### 6. YAML Syntax Error
+
+**Error:**
+```
+Error: Configuration error: invalid type: string "true", expected a boolean
+Error: while parsing a block mapping
+```
+
+**Cause:** Invalid YAML syntax.
+
+**Common mistakes:**
+
+**Wrong - Quotes around boolean:**
+```yaml
+enable_auth: "true"  # This is a string, not a boolean
+```
+
+**Correct:**
+```yaml
+enable_auth: true
+```
+
+**Wrong - Mixed spaces and tabs:**
+```yaml
+database:
+	url: postgresql://...  # Tab used for indentation
+```
+
+**Correct - Use spaces only:**
+```yaml
+database:
+  url: postgresql://...  # 2 spaces
+```
+
+**Wrong - Missing space after colon:**
+```yaml
+level:debug  # No space after colon
+```
+
+**Correct:**
+```yaml
+level: debug  # Space after colon
+```
+
+**Validate YAML syntax:**
+```bash
+# Using Python
+python3 -c "import yaml; yaml.safe_load(open('config.yaml'))"
+
+# Using yq
+yq eval config.yaml
+
+# Using Ruby
+ruby -ryaml -e "YAML.load_file('config.yaml')"
+```
+
+### 7. Environment Variable Not Working
+
+**Error:** Configuration value not being overridden by environment variable.
+
+**Cause:** Incorrect environment variable format.
+
+**Correct format:**
+```bash
+ATTUNE__SECTION__KEY=value
+```
+
+**Common mistakes:**
+
+**Wrong - Single underscore:**
+```bash
+ATTUNE_DATABASE_URL=...  # Wrong
+```
+
+**Correct - Double underscore:**
+```bash
+ATTUNE__DATABASE__URL=...  # Correct
+```
+
+**Wrong - Missing ATTUNE prefix:**
+```bash
+DATABASE__URL=...  # Wrong
+```
+
+**Correct - With ATTUNE prefix:**
+```bash
+ATTUNE__DATABASE__URL=...  # Correct
+```
+
+**Wrong - Incorrect case:**
+```bash
+attune__database__url=...  # Wrong (lowercase prefix)
+```
+
+**Correct - ATTUNE in uppercase:**
+```bash
+ATTUNE__DATABASE__URL=...  # Correct
+```
+
+**For arrays (comma-separated):**
+```bash
+ATTUNE__SERVER__CORS_ORIGINS="http://localhost:3000,http://localhost:5173"
+```
+
+### 8. Port Already in Use
+
+**Error:**
+```
+Error: Address already in use (os error 98)
+```
+
+**Cause:** Another process is using port 8080.
+
+**Solution:**
+
+1. **Find the process:**
+   ```bash
+   lsof -i :8080
+   # Or
+   netstat -tulpn | grep 8080
+   ```
+
+2. **Kill the process:**
+   ```bash
+   kill <PID>
+   ```
+
+3. **Or change the port:**
+   ```yaml
+   server:
+     port: 8081
+   ```
+   
+   Or with environment variable:
+   ```bash
+   ATTUNE__SERVER__PORT=8081 cargo run --bin attune-api
+   ```
+
+### 9. CORS Issues
+
+**Error in browser console:**
+```
+Access to fetch at 'http://localhost:8080/api/v1/...' from origin 'http://localhost:3000' 
+has been blocked by CORS policy
+```
+
+**Cause:** Frontend origin not in allowed CORS origins.
+
+**Solution:**
+
+Add your frontend URL to CORS origins:
+```yaml
+server:
+  cors_origins:
+    - http://localhost:3000
+    - http://localhost:5173  # Vite default
+```
+
+Or use environment variable:
+```bash
+export ATTUNE__SERVER__CORS_ORIGINS="http://localhost:3000,http://localhost:5173"
+```
+
+### 10. Configuration Changes Not Taking Effect
+
+**Cause:** Cached binary or incorrect environment.
+
+**Solution:**
+
+1. **Rebuild the application:**
+   ```bash
+   cargo clean
+   cargo build --bin attune-api
+   ```
+
+2. **Check which config file is being loaded:**
+   ```bash
+   ATTUNE__LOG__LEVEL=debug cargo run --bin attune-api 2>&1 | grep -i config
+   ```
+
+3. **Verify environment:**
+   ```bash
+   env | grep ATTUNE
+   ```
+
+4. **Use explicit config file:**
+   ```bash
+   ATTUNE_CONFIG=./config.development.yaml cargo run --bin attune-api
+   ```
+
+## Advanced Diagnostics
+
+### Debug Configuration Loading
+
+Enable debug logging to see configuration details:
+
+```bash
+ATTUNE__LOG__LEVEL=debug cargo run --bin attune-api 2>&1 | tee debug.log
+```
+
+Look for lines containing:
+- "Configuration loaded"
+- "Environment:"
+- "Loaded configuration from"
+
+### Verify Configuration Merging
+
+Test the configuration priority:
+
+1. **Base config only:**
+   ```bash
+   cargo run --bin attune-api
+   ```
+
+2. **With environment-specific config:**
+   ```bash
+   ATTUNE__ENVIRONMENT=development cargo run --bin attune-api
+   ```
+
+3. **With environment variable override:**
+   ```bash
+   ATTUNE__SERVER__PORT=9999 cargo run --bin attune-api
+   ```
+
+### Check Database Connection
+
+Test database connectivity separately:
+
+```bash
+# Using psql
+psql -U postgres -h localhost -d attune -c "SELECT version();"
+
+# Using sqlx-cli
+sqlx database create --database-url postgresql://postgres:postgres@localhost/attune
+sqlx migrate run --database-url postgresql://postgres:postgres@localhost/attune
+```
+
+### Validate All Configuration Values
+
+```bash
+# Dump configuration (be careful - may contain secrets!)
+ATTUNE__LOG__LEVEL=debug cargo run --bin attune-api 2>&1 | grep -A 50 "Configuration loaded"
+```
+
+## Security Checklist
+
+When troubleshooting, ensure:
+
+- [ ] Secrets are not logged or displayed
+- [ ] Configuration files with secrets are in `.gitignore`
+- [ ] Production secrets use environment variables
+- [ ] File permissions are restrictive (`chmod 600 config.yaml`)
+- [ ] JWT secrets are cryptographically strong (64+ bytes)
+- [ ] Encryption keys are at least 32 characters
+
+## Getting More Help
+
+### Enable Verbose Logging
+
+```bash
+RUST_LOG=debug,attune_common=trace cargo run --bin attune-api
+```
+
+### Check Application Logs
+
+```bash
+# If logging to file
+tail -f /var/log/attune/attune.log
+
+# With pretty formatting
+ATTUNE__LOG__FORMAT=pretty cargo run --bin attune-api
+```
+
+### Validate Configuration Programmatically
+
+Create a test file `check_config.rs`:
+
+```rust
+use attune_common::config::Config;
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let config = Config::load()?;
+    config.validate()?;
+    println!("✓ Configuration is valid");
+    println!("Environment: {}", config.environment);
+    println!("Database URL: {}", config.database.url);
+    println!("Server: {}:{}", config.server.host, config.server.port);
+    Ok(())
+}
+```
+
+Run it:
+```bash
+cargo run --bin check_config
+```
+
+## Reference
+
+- [Configuration Guide](configuration.md) - Complete reference
+- [Migration Guide](env-to-yaml-migration.md) - Migrating from .env
+- [Quick Start](quick-start.md) - Getting started
+- [CONFIG_README.md](../CONFIG_README.md) - Quick reference
+
+## Common Configuration Patterns
+
+### Development Setup
+
+```yaml
+environment: development
+database:
+  url: postgresql://postgres:postgres@localhost:5432/attune
+  log_statements: true
+server:
+  host: 127.0.0.1
+  port: 8080
+log:
+  level: debug
+  format: pretty
+security:
+  jwt_secret: dev-secret-change-in-production
+  encryption_key: dev-key-at-least-32-characters-long
+  enable_auth: true
+```
+
+### Production Setup
+
+```yaml
+environment: production
+database:
+  url: postgresql://user:pass@db.example.com/attune
+  max_connections: 100
+server:
+  host: 0.0.0.0
+  cors_origins:
+    - https://app.example.com
+log:
+  level: info
+  format: json
+  file: /var/log/attune/attune.log
+```
+
+With environment variables:
+```bash
+export ATTUNE__SECURITY__JWT_SECRET=$(cat /run/secrets/jwt_secret)
+export ATTUNE__SECURITY__ENCRYPTION_KEY=$(cat /run/secrets/encryption_key)
+```
+
+### Testing Setup
+
+```yaml
+environment: test
+database:
+  url: postgresql://postgres:postgres@localhost:5432/attune_test
+server:
+  port: 0  # Random port
+log:
+  level: warn
+security:
+  jwt_secret: test-secret-not-secure
+  encryption_key: test-key-at-least-32-characters-long
+```
+
+---
+
+If you continue to experience issues, please check the [GitHub Issues](https://github.com/yourusername/attune/issues) or open a new issue with:
+1. Error message
+2. Your configuration (with secrets redacted)
+3. Output of `cargo --version` and `rustc --version`
+4. Operating system and PostgreSQL version