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

```bash
# 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

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

```bash
# 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.

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

## Health Checks

All services include health checks:

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

## Backup and Restore

### Database Backup

```bash
# 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

```bash
# 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

```bash
# All services
docker compose logs -f

# Specific service
docker compose logs -f api

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

### Resource Usage

```bash
# Container stats
docker stats

# Disk usage
docker system df -v
```

## Troubleshooting

### Common Issues

**Database connection failed**
```bash
# Check PostgreSQL is running
docker compose ps

# Check logs
docker compose logs postgres

# Verify credentials in .env match
```

**Migrations failing**
```bash
# Check current migration version
docker compose exec api alembic current

# Manual upgrade
docker compose exec api alembic upgrade head
```

**Permission denied on repos**
```bash
# Fix permissions
docker compose exec api chown -R appuser:appuser /data/repos
```

## Updates

### Rolling Update

```bash
# 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

```bash
# 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

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

## Resources

- [Docker Documentation](https://docs.docker.com/)
- [Docker Compose Reference](https://docs.docker.com/compose/)
- [Traefik Documentation](https://doc.traefik.io/traefik/)