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
parent 6807f449b7
commit 83f94b1f09
31 changed files with 5498 additions and 0 deletions
@@ -0,0 +1,266 @@
+# 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/)