alex
e7819bfc82
- 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
114 lines
3.0 KiB
Markdown
114 lines
3.0 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 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
|