headquarter/docs/deployment/docker.md

Docker Deployment Guide

Overview

Headquarter is deployed as a multi-container Docker application using Docker Compose. The stack includes:

• API (FastAPI/Python)
• Web (React/Vite)
• PostgreSQL (Database)
• Redis (Cache)

Quick Start

Prerequisites

• Docker Engine 20.10+
• Docker Compose 2.0+
• 2GB RAM minimum
• 10GB disk space

Development Deployment

# Clone repository
git clone https://github.com/your-org/headquarter.git
cd headquarter

# Copy environment file
cp .env.example .env
# Edit .env with your settings

# Start all services
docker compose up -d

# Run database migrations
docker compose exec api alembic upgrade head

# Access the app
# Frontend: http://localhost:5173
# API: http://localhost:8000

Production Deployment

# Use production compose file
cp .env.example .env
# Configure production values in .env

docker compose -f docker-compose.traefik.yml up -d

# Run migrations
docker compose -f docker-compose.traefik.yml exec api alembic upgrade head

Configuration

Environment Variables

Required variables:

# Domains
API_DOMAIN=api.yourdomain.com
WEB_DOMAIN=app.yourdomain.com

# Database
POSTGRES_USER=headquarter
POSTGRES_PASSWORD=secure-password
POSTGRES_DB=headquarter

# Authentik OAuth
AUTHENTIK_DOMAIN=auth.yourdomain.com
AUTHENTIK_CLIENT_ID=your-client-id
AUTHENTIK_CLIENT_SECRET=your-client-secret
AUTHENTIK_APPLICATION_SLUG=headquarter

# Session
SESSION_SECRET=your-session-secret-min-32-chars

# Storage
REPO_BASE_PATH=/data/repos

Volume Mounts

Volume	Container Path	Purpose
postgres_data	/var/lib/postgresql/data	Database persistence
repo_data	/data/repos	Git repositories
avatar_uploads	/app/uploads	User avatars

Docker Compose Files

docker-compose.yml (Development)

Standard development setup with:

• Hot reload for API
• Vite dev server for frontend
• Direct port access
• Local PostgreSQL

docker-compose.traefik.yml (Production)

Production setup with:

• Traefik reverse proxy
• Let's Encrypt SSL
• External Traefik network
• Optimized builds

SSL/TLS

Development

Self-signed certificates or HTTP only.

Production

Automatic Let's Encrypt certificates via Traefik.

# Traefik labels for SSL
traefik.http.routers.api.tls=true
traefik.http.routers.api.tls.certresolver=letsencrypt

Health Checks

All services include health checks:

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
  interval: 30s
  timeout: 10s
  retries: 3

Backup and Restore

Database Backup

# Automated daily backup
docker compose exec postgres pg_dump -U headquarter headquarter > backup.sql

# Restore
docker compose exec -T postgres psql -U headquarter < backup.sql

Repository Backup

# Backup repos volume
docker run --rm -v headquarter_repo_data:/data -v $(pwd):/backup alpine tar czf /backup/repos.tar.gz /data

# Restore
docker run --rm -v headquarter_repo_data:/data -v $(pwd):/backup alpine tar xzf /backup/repos.tar.gz -C /

Monitoring

Logs

# All services
docker compose logs -f

# Specific service
docker compose logs -f api

# Last 100 lines
docker compose logs --tail=100 api

Resource Usage

# Container stats
docker stats

# Disk usage
docker system df -v

Troubleshooting

Common Issues

Database connection failed

# Check PostgreSQL is running
docker compose ps

# Check logs
docker compose logs postgres

# Verify credentials in .env match

Migrations failing

# Check current migration version
docker compose exec api alembic current

# Manual upgrade
docker compose exec api alembic upgrade head

Permission denied on repos

# Fix permissions
docker compose exec api chown -R appuser:appuser /data/repos

Updates

Rolling Update

# Pull latest images
docker compose pull

# Restart with new images
docker compose up -d

# Run migrations if needed
docker compose exec api alembic upgrade head

Zero-Downtime Update

# Scale API to 2 instances
docker compose up -d --scale api=2

# Update one instance at a time
# (Requires load balancer configuration)

Security Best Practices

1. Use strong passwords for database and session secret
2. Enable HTTPS in production
3. Keep images updated with security patches
4. Use read-only volumes where possible
5. Limit container capabilities
6. Use secrets management for sensitive data

# Example security hardening
api:
  read_only: true
  security_opt:
    - no-new-privileges:true
  cap_drop:
    - ALL
  cap_add:
    - CHOWN
    - SETGID
    - SETUID

Resources

• Docker Documentation
• Docker Compose Reference
• Traefik Documentation