Files

T

alex e7819bfc82 feat: implement docker infrastructure (US-001)

- Add docker-compose.yml with postgres, redis, api, and web services
- Add multi-stage Dockerfile for API (Python 3.11)
- Add multi-stage Dockerfile for web (Node.js 20 + nginx)
- Add Makefile with common development commands
- Add .env.example with all required environment variables
- Add placeholder pyproject.toml and package.json for builds
- Configure health checks for all services
- Setup persistent volumes for postgres, redis, and repos
- Run services as non-root users

2026-05-16 17:44:39 +00:00

3.0 KiB

Raw Blame History

Docker Infrastructure Specification

Purpose

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

Requirements

Requirement: Docker Compose Setup

The system SHALL provide a docker-compose.yml with all platform services.

Scenario: Service definitions

GIVEN the development environment
THEN docker-compose.yml SHALL define:
- PostgreSQL database with health checks
- Redis cache with health checks
- Traefik reverse proxy with dashboard
- Authentik authentication server
- API service (FastAPI)
- Web frontend (React/Vite)

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.

Scenario: Environment setup

GIVEN a new developer
WHEN they set up the project
THEN .env.example SHALL document:
- Database connection strings
- Redis connection strings
- Authentik configuration
- JWT secrets
- Docker volume paths
- 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

3.0 KiB Raw Blame History