423 lines
10 KiB
Markdown
423 lines
10 KiB
Markdown
|
# 🔧 Environment Variables
|
||
|
|
|
||
|
|
NoteDiscovery supports environment variables to override configuration settings, allowing different behavior in different deployment environments (local, staging, production).
|
||
|
|
|
||
|
|
## 📋 Available Environment Variables
|
||
|
|
|
||
|
|
### Core Settings
|
||
|
|
|
||
|
|
| Variable | Type | Default | Description |
|
||
|
|
|----------|------|---------|-------------|
|
||
|
|
| `PORT` | integer | `8000` | HTTP port for the application (Docker, run.py) |
|
||
|
|
|
||
|
|
> **Note**: Advanced server settings (CORS origins, debug mode) are configured via `config.yaml` only, not via environment variables. See [config.yaml](#advanced-server-configuration) for details.
|
||
|
|
|
||
|
|
### Authentication
|
||
|
|
|
||
|
|
| Variable | Type | Default | Description |
|
||
|
|
|----------|------|---------|-------------|
|
||
|
|
| `AUTHENTICATION_ENABLED` | boolean | `config.yaml` | Enable/disable authentication |
|
||
|
|
| `AUTHENTICATION_PASSWORD_HASH` | string | `config.yaml` | Bcrypt password hash |
|
||
|
|
| `AUTHENTICATION_SECRET_KEY` | string | `config.yaml` | Session secret key (for session security) |
|
||
|
|
|
||
|
|
### Demo Mode
|
||
|
|
|
||
|
|
| Variable | Type | Default | Description |
|
||
|
|
|----------|------|---------|-------------|
|
||
|
|
| `DEMO_MODE` | boolean | `false` | Enable demo mode (enables rate limiting and other demo restrictions) |
|
||
|
|
|
||
|
|
## 🎯 Configuration Priority
|
||
|
|
|
||
|
|
Configuration is loaded in this order (later overrides earlier):
|
||
|
|
|
||
|
|
1. **`config.yaml`** - Default configuration file
|
||
|
|
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):
|
||
|
|
|
||
|
|
### CORS (Cross-Origin Resource Sharing)
|
||
|
|
|
||
|
|
```yaml
|
||
|
|
server:
|
||
|
|
# List of allowed origins for CORS
|
||
|
|
# Default: ["*"] allows all origins (fine for self-hosted)
|
||
|
|
# Production: specify your domains
|
||
|
|
allowed_origins: ["*"]
|
||
|
|
|
||
|
|
# Examples for production:
|
||
|
|
# allowed_origins: ["http://localhost:8000", "https://yourdomain.com"]
|
||
|
|
# allowed_origins: ["https://*.yourdomain.com"] # Wildcard subdomain
|
||
|
|
```
|
||
|
|
|
||
|
|
**Security Note:**
|
||
|
|
- `["*"]` is **safe for self-hosted** deployments on private networks
|
||
|
|
- For **public deployments**, specify exact origins to prevent unauthorized API access
|
||
|
|
- This prevents CSRF attacks when authentication is enabled
|
||
|
|
|
||
|
|
### Debug Mode
|
||
|
|
|
||
|
|
```yaml
|
||
|
|
server:
|
||
|
|
# Enable detailed error messages in API responses
|
||
|
|
# Default: false (production-safe)
|
||
|
|
# Set to true for development/troubleshooting
|
||
|
|
debug: false
|
||
|
|
```
|
||
|
|
|
||
|
|
**⚠️ CRITICAL**: Never enable `debug: true` in production!
|
||
|
|
|
||
|
|
When `debug: true`:
|
||
|
|
- Full error stack traces are returned to users
|
||
|
|
- Internal paths and system details are exposed
|
||
|
|
- Security vulnerabilities may be revealed
|
||
|
|
|
||
|
|
When `debug: false` (recommended):
|
||
|
|
- Generic error messages are returned
|
||
|
|
- Full error details are logged server-side only
|
||
|
|
- Production-safe error handling
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 📚 Related Documentation
|
||
|
|
|
||
|
|
- **Authentication**: [AUTHENTICATION.md](AUTHENTICATION.md)
|
||
|
|
- **Render Deployment**: [DEPLOYMENT_RENDER.md](DEPLOYMENT_RENDER.md)
|
||
|
|
- **API Rate Limiting**: [API.md](API.md#rate-limiting)
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
**Pro Tip:** Use environment variables for **deployment-specific** settings, and `config.yaml` for **application defaults**. This keeps your configuration flexible and maintainable! 🎯
|
||
|
|
|