diff --git a/documentation/ENVIRONMENT_VARIABLES.md b/documentation/ENVIRONMENT_VARIABLES.md index 8001206..4b32ef2 100644 --- a/documentation/ENVIRONMENT_VARIABLES.md +++ b/documentation/ENVIRONMENT_VARIABLES.md @@ -34,335 +34,6 @@ Configuration is loaded in this order (later overrides earlier): 2. **Environment Variables** - Runtime overrides 3. **Command Line** - Highest priority (if applicable) -## 💡 Common Use Cases - -### Use Case 1: Local Development (No Auth) - -**Local setup:** -```bash -# No environment variables needed -# Uses config.yaml defaults (auth disabled) -python run.py -``` - -**`config.yaml`:** -```yaml -authentication: - enabled: false -``` - -**Result:** ✅ No authentication, quick local testing - ---- - -### Use Case 2: Public Demo (Auth + Rate Limiting) - -**Render deployment:** -```yaml -# render.yaml -envVars: - - key: DEMO_MODE - value: "true" - - key: AUTHENTICATION_ENABLED - value: "true" -``` - -**`config.yaml`:** -```yaml -authentication: - enabled: false # Overridden by AUTHENTICATION_ENABLED=true -``` - -**Result:** ✅ Demo mode enabled (rate limiting + restrictions), authentication enabled - ---- - -### Use Case 3: Private Demo (Custom Password & Secret Key) - -**Generate password hash and secret key:** -```bash -# Generate password hash -python generate_password.py -# Enter password: mysecurepassword -# Generated hash: $2b$12$... - -# Generate secret key -python -c "import secrets; print(secrets.token_hex(32))" -# Generated key: a1b2c3d4e5f6... -``` - -**Render deployment:** -```yaml -envVars: - - key: AUTHENTICATION_ENABLED - value: "true" - - key: AUTHENTICATION_PASSWORD_HASH - value: "$2b$12$..." # Your generated hash - - key: AUTHENTICATION_SECRET_KEY - value: "a1b2c3d4e5f6..." # Your generated key -``` - -**Result:** ✅ Custom password and secure session key for production demo - ---- - -### Use Case 4: Docker Compose (Local Development) - -**`docker-compose.yml`:** -```yaml -services: - notediscovery: - image: ghcr.io/gamosoft/notediscovery:latest - ports: - - "8000:8000" - environment: - - AUTHENTICATION_ENABLED=false - - DEMO_MODE=false - volumes: - - ./data:/app/data -``` - -**Result:** ✅ Local deployment without restrictions (no auth, no rate limiting) - ---- - -### Use Case 5: Custom Port - -**Run on port 3000 instead of 8000:** - -**Local (run.py):** -```bash -PORT=3000 python run.py -# → Runs on http://localhost:3000 -``` - -**Docker:** -```bash -docker run -p 3000:3000 -e PORT=3000 ghcr.io/gamosoft/notediscovery:latest -``` - -**Docker Compose:** -```yaml -services: - notediscovery: - image: ghcr.io/gamosoft/notediscovery:latest - ports: - - "3000:3000" # Host:Container - environment: - - PORT=3000 -``` - -**Result:** ✅ App runs on custom port - ---- - -## 🔐 Authentication Examples - -### Example 1: Enable Auth via Environment - -**Without environment variables:** -```bash -# Uses config.yaml defaults -🔐 Authentication DISABLED (from config.yaml) -✅ Production mode - Rate limiting disabled -``` - -**With environment variables (demo mode):** -```bash -export DEMO_MODE=true -export AUTHENTICATION_ENABLED=true -python run.py - -# Output: -🎭 DEMO MODE enabled - Rate limiting active -🔐 Authentication ENABLED (from AUTHENTICATION_ENABLED env var) -``` - -### Example 2: Demo Deployment - -**Public demo with restrictions:** -```bash -export DEMO_MODE=true -export AUTHENTICATION_ENABLED=true -export AUTHENTICATION_PASSWORD_HASH='$2b$12$custom_hash' -export AUTHENTICATION_SECRET_KEY='your_random_secret_key' -python run.py - -# Output: -🎭 DEMO MODE enabled - Rate limiting active -🔐 Authentication ENABLED (from AUTHENTICATION_ENABLED env var) -🔑 Password hash loaded from AUTHENTICATION_PASSWORD_HASH env var -🔐 Secret key loaded from AUTHENTICATION_SECRET_KEY env var -``` - -**Private instance (no restrictions):** -```bash -# No environment variables needed -python run.py - -# Output: -✅ Production mode - Rate limiting disabled -🔐 Authentication DISABLED (from config.yaml) -``` - -## 📝 Boolean Values - -Environment variables accept multiple formats for boolean values: - -**True values:** -- `true`, `True`, `TRUE` -- `1` -- `yes`, `Yes`, `YES` - -**False values:** -- `false`, `False`, `FALSE` -- `0` -- `no`, `No`, `NO` -- Not set (uses config.yaml default) - -**Examples:** -```bash -AUTHENTICATION_ENABLED=true # ✅ Enabled -AUTHENTICATION_ENABLED=1 # ✅ Enabled -AUTHENTICATION_ENABLED=yes # ✅ Enabled -AUTHENTICATION_ENABLED=false # ❌ Disabled -AUTHENTICATION_ENABLED=0 # ❌ Disabled -# Not set # Uses config.yaml -``` - -## 🚀 Deployment Scenarios - -### Scenario 1: Same Codebase, Different Environments - -**Repository structure:** -``` -config.yaml # Default: auth disabled (for local dev) -render.yaml # Render: AUTHENTICATION_ENABLED=true -docker-compose.yml # Docker: AUTHENTICATION_ENABLED=false (or not set) -``` - -**Benefits:** -- ✅ Single codebase -- ✅ No code changes between environments -- ✅ Environment-specific security - -### Scenario 2: Team Collaboration - -**Team workflow:** -```bash -# Developer 1 (local, no auth) -git clone repo -python run.py -# → No auth needed for local testing - -# Developer 2 (local, testing auth) -AUTHENTICATION_ENABLED=true python run.py -# → Tests authentication locally - -# Production (Render) -# → AUTHENTICATION_ENABLED=true in render.yaml -# → Always requires authentication -``` - -### Scenario 3: CI/CD Pipeline - -**GitHub Actions:** -```yaml -- name: Test with auth disabled - run: | - export AUTHENTICATION_ENABLED=false - pytest tests/ - -- name: Test with auth enabled - run: | - export AUTHENTICATION_ENABLED=true - pytest tests/auth/ -``` - -## 🔍 Checking Current Configuration - -The application prints its configuration on startup: - -```bash -python run.py - -# Output: -🎭 DEMO MODE enabled - Rate limiting active -🔐 Authentication ENABLED (from AUTHENTICATION_ENABLED env var) -🔑 Password hash loaded from AUTHENTICATION_PASSWORD_HASH env var -🔐 Secret key loaded from AUTHENTICATION_SECRET_KEY env var -``` - -## ⚙️ Advanced: All Environment Variables - -**Full demo deployment example:** -```bash -export PORT=8080 -export DEMO_MODE=true -export AUTHENTICATION_ENABLED=true -export AUTHENTICATION_PASSWORD_HASH='$2b$12$...' -export AUTHENTICATION_SECRET_KEY='your_random_secret_key_here' - -python run.py -``` - -**Docker example:** -```dockerfile -ENV PORT=8000 -ENV DEMO_MODE=true -ENV AUTHENTICATION_ENABLED=true -ENV AUTHENTICATION_PASSWORD_HASH='$2b$12$...' -ENV AUTHENTICATION_SECRET_KEY='your_random_secret_key_here' -``` - -## 📊 Quick Reference Table - -| Scenario | `DEMO_MODE` | `AUTHENTICATION_ENABLED` | Behavior | -|----------|-------------|---------------|----------| -| **Local Dev** | Not set | Not set | No restrictions, quick testing | -| **Local Auth Testing** | Not set | `true` | Auth only, no rate limits | -| **Public Demo** | `true` | `true` | Full restrictions + auth | -| **Private Instance** | Not set | `true` | Auth only, self-hosted | -| **Read-Only Demo** | `true` | Not set | Rate limited, no auth | - -## 🆘 Troubleshooting - -### "Authentication not working" - -**Check startup logs:** -``` -🔐 Authentication DISABLED (from config.yaml) -``` - -**Fix:** Set environment variable -```bash -export AUTHENTICATION_ENABLED=true -``` - -### "Wrong password accepted" - -**Check if password hash is loaded:** -``` -🔑 Password hash loaded from AUTHENTICATION_PASSWORD_HASH env var -``` - -**If not shown:** Environment variable not set, using `config.yaml` - -### "Can't disable auth in Render" - -**Option 1:** Remove from `render.yaml` -```yaml -# Remove or comment out: -# - key: AUTHENTICATION_ENABLED -# value: "true" -``` - -**Option 2:** Explicitly disable -```yaml -- key: AUTHENTICATION_ENABLED - value: "false" -``` - ## 🔧 Advanced Server Configuration The following settings are available in `config.yaml` only (not via environment variables): @@ -413,7 +84,6 @@ When `debug: false` (recommended): ## 📚 Related Documentation - **Authentication**: [AUTHENTICATION.md](AUTHENTICATION.md) -- **Render Deployment**: [DEPLOYMENT_RENDER.md](DEPLOYMENT_RENDER.md) - **API Rate Limiting**: [API.md](API.md#rate-limiting) ---