Fusion
9b04760423
- 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
115 lines
3.3 KiB
Markdown
115 lines
3.3 KiB
Markdown
# 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
|