headquarter/openspec/specs/docker-infrastructure/spec.md

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