Docker Compose¶

Services¶

flowchart LR
    App[aima-app]
    Worker[aima-celery-worker]
    Beat[aima-celery-beat]
    Redis[aima-redis]
    PG[aima-postgres]
    Chroma[aima-chroma volume]
    App --> Redis
    Worker --> Redis
    Beat --> Redis
    App --> PG
    App --> Chroma
    App --> Storage[(aima-data / storage)]
    Worker --> Storage

Service	Image / build	Purpose
app (`aima-app`)	`aima-app:latest`	FastAPI + static
celery_worker	same	Celery worker
celery_beat	same	Celery Beat (backup, self-heal)
redis (`aima-redis`)	redis:7-alpine	Broker, cache
postgres (`aima-postgres`)	postgres	Prod DB
mock_rag (`aima-mock-rag`)	profile `mock-rag`	Demo external RAG

Files¶

File	Purpose
`docker-compose.yml`	Local development / base
`docker-compose.prod.yml`	Production VPS overlay
`Dockerfile`	Multi-stage build

Local run¶

cp .env.example .env
# Edit SECRET_KEY, AGE keys

docker compose up -d --build
docker compose logs -f app

Application: http://localhost:8001

Optional mock RAG:

docker compose --profile mock-rag up -d mock_rag

Production¶

docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d --build

Volumes and mounts¶

Volume / mount	Path	Data
`aima-data` / `./medinsight.db`	DB (SQLite path from `.env.example`)
`aima-postgres`	PostgreSQL data
`aima-chroma`	Chroma RAG
`./storage`	Documents, DICOM
`./backups` / `aima-backups`	Archives
`./site:/app/site:ro`	Built MkDocs documentation

Warning

Do not remove volumes on docker compose down without a backup.

Compose variables¶

Passed via env_file: .env or environment: in the compose file.

Restart vs recreate

docker compose restart app does not pick up new .env keys. Use docker compose up -d --force-recreate app celery_worker or ./deploy.sh production.

Build¶

Dockerfile tuned for VPS:

PIP_DEFAULT_TIMEOUT=300
PIP_RETRIES=5

Useful commands¶

docker compose build app
docker compose exec app bash
docker compose exec app bash -c 'python scripts/run_alembic_migrate.py'
./scripts/docker_cleanup.sh deploy

Healthcheck¶

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:8001/health/ready"]
  interval: 30s
  timeout: 10s
  retries: 3

Ports¶

Service	Host:Container
app	8001:8001 (`APP_PORT`)
redis	6380:6379 (`REDIS_HOST_PORT`)
mock_rag	see compose profile