alex/headquarter
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
014b88ee564a1a69a4a6ee33c52b536c4f6ec330
headquarter/docs/deployment/environment.md
T
Fusion 83f94b1f09 docs: comprehensive documentation overhaul 
Add complete documentation structure:
- Frontend architecture documentation
- Database schema documentation
- Deployment guides (Docker, Traefik, Authentik, Environment)
- Development guides (Setup, Testing, Contributing, Quality Gates)
- Deployment architecture documentation
- Updated docs README with complete navigation

All new features and APIs are now documented.
Quality gates: docs only, no code changes
2026-05-19 14:18:20 +02:00

269 lines
7.9 KiB
Markdown
Raw Blame History

# Environment Variables Reference
## Overview
This document describes all environment variables used by Headquarter. Variables are categorized by component and purpose.
## Required Variables
These variables must be set for the application to function:
### Domains
| Variable | Default | Description |
|----------|---------|-------------|
| `API_DOMAIN` | `localhost` | API server domain (e.g., `api.example.com`) |
| `WEB_DOMAIN` | `localhost` | Web frontend domain (e.g., `app.example.com`) |
### Database
| Variable | Default | Description |
|----------|---------|-------------|
| `POSTGRES_USER` | `headquarter` | PostgreSQL username |
| `POSTGRES_PASSWORD` | `headquarter` | PostgreSQL password (change in production!) |
| `POSTGRES_DB` | `headquarter` | PostgreSQL database name |
### Authentication
| Variable | Default | Description |
|----------|---------|-------------|
| `AUTHENTIK_DOMAIN` | `authentik.local` | Authentik server domain |
| `AUTHENTIK_CLIENT_ID` | `headquarter-web` | OAuth client ID from Authentik |
| `AUTHENTIK_CLIENT_SECRET` | `change-me` | OAuth client secret (change immediately!) |
| `AUTHENTIK_APPLICATION_SLUG` | `headquarter-web` | Authentik application slug |
| `SESSION_SECRET` | `change-me-session-secret` | Secret for signing session cookies (min 32 chars) |
## Optional Variables
### Application
| Variable | Default | Description |
|----------|---------|-------------|
| `APP_ENV` | `development` | Environment: `development`, `staging`, `production` |
| `LOG_LEVEL` | `INFO` | Logging level: `DEBUG`, `INFO`, `WARNING`, `ERROR` |
### Database
| Variable | Default | Description |
|----------|---------|-------------|
| `DATABASE_URL` | (constructed) | Full PostgreSQL connection URL |
| `POSTGRES_HOST` | `postgres` | PostgreSQL hostname |
| `POSTGRES_PORT` | `5432` | PostgreSQL port |
When `DATABASE_URL` is not set, it's constructed from:
```
postgresql+asyncpg://POSTGRES_USER:POSTGRES_PASSWORD@POSTGRES_HOST:POSTGRES_PORT/POSTGRES_DB
```
### URLs
| Variable | Default | Description |
|----------|---------|-------------|
| `API_PUBLIC_URL` | (constructed) | Public API URL (e.g., `https://api.example.com`) |
| `WEB_PUBLIC_URL` | (constructed) | Public web URL (e.g., `https://app.example.com`) |
Constructed from domains when not set:
```
API: https://API_DOMAIN (production) or http://API_DOMAIN:8000 (development)
WEB: https://WEB_DOMAIN (production) or http://WEB_DOMAIN:5173 (development)
```
### Authentik Overrides
| Variable | Default | Description |
|----------|---------|-------------|
| `AUTHENTIK_AUTHORIZE_URL` | (constructed) | OAuth authorization endpoint |
| `AUTHENTIK_TOKEN_URL` | (constructed) | OAuth token endpoint |
| `AUTHENTIK_JWKS_URL` | (constructed) | JWKS endpoint |
| `AUTHENTIK_ISSUER` | (constructed) | OAuth issuer URL |
| `AUTHENTIK_AUDIENCE` | `headquarter-web` | Token audience |
Constructed URLs:
```
https://AUTHENTIK_DOMAIN/application/o/authorize/
https://AUTHENTIK_DOMAIN/application/o/token/
https://AUTHENTIK_DOMAIN/application/o/AUTHENTIK_APPLICATION_SLUG/jwks/
https://AUTHENTIK_DOMAIN/application/o/AUTHENTIK_APPLICATION_SLUG/
```
### Session
| Variable | Default | Description |
|----------|---------|-------------|
| `SESSION_TTL_HOURS` | `24` | Session cookie lifetime in hours |
| `COOKIE_DOMAIN` | (none) | Cookie domain (set for cross-subdomain) |
| `COOKIE_SECURE` | `true` (prod) | Secure cookie flag |
| `COOKIE_SAMESITE` | `lax` | SameSite cookie attribute |
### Storage
| Variable | Default | Description |
|----------|---------|-------------|
| `REPO_BASE_PATH` | `/data/repos` | Base path for git repositories |
| `UPLOAD_DIR` | `uploads` | Directory for file uploads |
### Development
| Variable | Default | Description |
|----------|---------|-------------|
| `VITE_API_BASE_URL` | `http://localhost:8000` | Frontend API URL |
## Docker Compose Variables
### Traefik
| Variable | Default | Description |
|----------|---------|-------------|
| `TRAEFIK_NETWORK` | `traefik` | Docker network name for Traefik |
| `TRAEFIK_CERT_RESOLVER` | `letsencrypt` | Certificate resolver name |
### Docker Specific
| Variable | Default | Description |
|----------|---------|-------------|
| `COMPOSE_PROJECT_NAME` | `headquarter` | Docker Compose project name |
## Configuration Examples
### Development
```bash
APP_ENV=development
API_DOMAIN=localhost
WEB_DOMAIN=localhost
DATABASE_URL=postgresql+asyncpg://headquarter:headquarter@localhost:5432/headquarter
AUTHENTIK_DOMAIN=authentik.local
AUTHENTIK_CLIENT_ID=headquarter-web
AUTHENTIK_CLIENT_SECRET=dev-secret
SESSION_SECRET=dev-session-secret-change-in-production
VITE_API_BASE_URL=http://localhost:8000
```
### Production
```bash
APP_ENV=production
API_DOMAIN=api.headquarter.example.com
WEB_DOMAIN=app.headquarter.example.com
POSTGRES_PASSWORD=very-secure-password-here
AUTHENTIK_DOMAIN=auth.example.com
AUTHENTIK_CLIENT_ID=your-uuid-from-authentik
AUTHENTIK_CLIENT_SECRET=your-secret-from-authentik
AUTHENTIK_APPLICATION_SLUG=headquarter-web
SESSION_SECRET=minimum-32-characters-long-secret-key
SESSION_TTL_HOURS=24
COOKIE_DOMAIN=.headquarter.example.com
TRAEFIK_NETWORK=web
TRAEFIK_CERT_RESOLVER=letsencrypt
REPO_BASE_PATH=/data/repos
```
### Testing
```bash
APP_ENV=testing
DATABASE_URL=postgresql+asyncpg://headquarter:headquarter@localhost:5432/headquarter_test
SESSION_SECRET=test-secret
AUTHENTIK_CLIENT_ID=test-client
AUTHENTIK_CLIENT_SECRET=test-secret
```
## Security Checklist
Before deploying to production, verify:
- [ ] `POSTGRES_PASSWORD` is strong and unique
- [ ] `AUTHENTIK_CLIENT_SECRET` is kept secret
- [ ] `SESSION_SECRET` is at least 32 characters
- [ ] `APP_ENV` is set to `production`
- [ ] `COOKIE_SECURE` is enabled
- [ ] `COOKIE_DOMAIN` is set for your domain
- [ ] No default secrets in production
- [ ] `.env` file is not committed to git
- [ ] `.env` file has restricted permissions (600)
## Troubleshooting
### Variable Not Set
```bash
# Error: "Environment variable not set"
# Solution: Export the variable or add to .env file
export SESSION_SECRET="your-secret-here"
```
### Invalid URL
```bash
# Error: "Invalid URL"
# Solution: Check domain variables don't include protocol
# Bad: API_DOMAIN=https://api.example.com
# Good: API_DOMAIN=api.example.com
```
### Database Connection Failed
```bash
# Check DATABASE_URL or individual components
# Verify PostgreSQL is running
# Check credentials match
```
## Migration from Old Config
If upgrading from older versions:
1. `JWT_SECRET` → Removed (not needed with session auth)
2. `ACCESS_TOKEN_TTL_MINUTES` → Removed
3. `REFRESH_TOKEN_TTL_DAYS` → Removed
4. `AUTHENTIK_AUDIENCE` → Now defaults to `AUTHENTIK_CLIENT_ID`
5. `AUTHENTIK_APPLICATION_SLUG` → New variable for URL construction
## Environment Files
### Files Structure
```
headquarter/
├── .env # Main environment (not committed)
├── .env.example # Example/template
├── apps/
│ ├── api/
│ │ └── .env # API-specific overrides
│ └── web/
│ └── .env # Frontend-specific overrides
└── docker-compose.traefik.yml # References .env
```
### Loading Order
1. System environment variables
2. `.env` file in project root
3. Component-specific `.env` files
4. Default values in code
Later values override earlier ones.
## Validation
The application validates required variables on startup:
```python
# Missing critical variable
if not settings.session_secret or settings.session_secret == "change-me":
logger.warning("SESSION_SECRET not configured properly!")
# Invalid configuration
if settings.app_env == "production" and "localhost" in settings.api_domain:
logger.warning("Using localhost in production!")
```
## Best Practices
1. **Never commit `.env` files**
2. **Use strong passwords** for database and secrets
3. **Rotate secrets** regularly
4. **Use different secrets** per environment
5. **Document custom variables** in this file
6. **Validate configuration** before deployment
Reference in New Issue View Git Blame Copy Permalink