Files

T

Fusion 9b04760423 docs: sync oauth-traefik-integration specs to main specs

- Update auth-oauth spec: configurable endpoints via environment variables
- Update docker-infrastructure spec: add traefik deployment mode
- Add traefik-deployment spec: new capability for reverse proxy deployment

2026-05-17 23:28:43 +02:00

3.3 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 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

3.3 KiB Raw Blame History