# Docker Infrastructure Specification

## Purpose

Provide a complete Docker-based development environment with all required services.

## Requirements

### Requirement: Docker Compose Setup

The system SHALL provide Docker Compose configurations for both development and traefik deployment.

#### Scenario: Development compose file
- GIVEN the development environment
- THEN `docker-compose.yml` SHALL define all platform services for local development

#### Scenario: Traefik compose file
- GIVEN the production deployment
- THEN `docker-compose.traefik.yml` SHALL define all platform services behind Traefik
- AND no ports SHALL be exposed directly (all traffic through Traefik)

### Requirement: Multi-Stage API Dockerfile

The system SHALL build the API using a multi-stage Docker build.

#### Scenario: API container build
- GIVEN the API source code
- WHEN building the Docker image
- THEN `apps/api/Dockerfile` SHALL:
  - Use Python 3.11+ base image
  - Install dependencies in a builder stage
  - Copy only necessary files to production stage
  - Run as non-root user
  - Expose port 8000

### Requirement: Web Frontend Dockerfile

The system SHALL build the web frontend for production deployment.

#### Scenario: Web container build
- GIVEN the frontend source code
- WHEN building the Docker image
- THEN `apps/web/Dockerfile` SHALL:
  - Use Node.js 20+ base image
  - Install dependencies
  - Build the production bundle with Vite
  - Serve via nginx or similar
  - Run as non-root user

### Requirement: Environment Configuration

The system SHALL document all required environment variables for both development and traefik deployment modes.

#### Scenario: Environment setup
- GIVEN a new developer or operator
- WHEN they set up the project
- THEN `.env.example` SHALL document all variables for both modes
- AND variables SHALL include:
  - Database connection strings
  - Redis connection strings
  - Authentik configuration
  - JWT secrets
  - Docker volume paths
  - Domain configuration for traefik mode
  - External service URLs

### Requirement: Service Health Checks

The system SHALL provide health checks for all services.

#### Scenario: Health verification
- GIVEN running services
- WHEN health checks are performed
- THEN each service reports healthy status
- AND unhealthy services are restarted automatically

### Requirement: Makefile Commands

The system SHALL provide common operational commands.

#### Scenario: Developer workflow
- GIVEN the project repository
- WHEN a developer runs make commands
- THEN these commands work:
  - `make up` - Start all services
  - `make down` - Stop all services
  - `make logs` - View service logs
  - `make migrate` - Run database migrations
  - `make test` - Run test suites
  - `make lint` - Run linting

### Requirement: Persistent Storage

The system SHALL persist git repositories across container restarts.

#### Scenario: Repository storage
- GIVEN the Docker setup
- THEN a dedicated volume SHALL mount at `/data/repos`
- AND repositories persist across container restarts

## Dependencies

- Docker 24.0+
- Docker Compose 2.20+
- Make

## Quality Gates

- `docker-compose config` validates without errors
- All services start successfully with `make up`
- Health checks pass for all services
- `pytest` must pass
- `mypy .` must pass
- `ruff check .` must pass