headquarter/docs/deployment/environment.md

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

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

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

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

# Error: "Environment variable not set"
# Solution: Export the variable or add to .env file
export SESSION_SECRET="your-secret-here"

Invalid URL

# 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

# 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:

# 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