builderadmin
/
NoteDiscovery
1
0
Fork 0
Code Issues Pull Requests 1 Packages Projects Releases Wiki Activity

doc updates

This commit is contained in:
Gamosoft 2025-11-25 17:24:36 +01:00
parent e0e4e457da
commit b47008d347
1 changed files with 0 additions and 330 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

330
documentation/ENVIRONMENT_VARIABLES.md
View File

@ -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)
---