Skip to main content

​
Overview

GAIA uses Docker Compose to run databases and services locally. In most cases, you don’t need to run Docker commands directly—mise automatically starts Docker when you run development commands.
Docker files are located in infra/docker/. The setup uses Nx to manage Docker as a project with its own targets.

​
Quick Start

mise dev          # Starts Docker + API + web
mise dev:api      # Starts Docker + API only
mise dev:web      # Starts Docker + web only
mise automatically runs nx run docker:docker:up before starting dev servers.

​
Manual Docker Control

If you need direct Docker control: 
# Start all services
docker compose -f infra/docker/docker-compose.yml up -d

# Stop services
docker compose -f infra/docker/docker-compose.yml down

# View logs
docker compose -f infra/docker/docker-compose.yml logs -f

​
Using Nx Docker Commands

# Start Docker services via Nx
npx nx run docker:docker:up

# Stop Docker services
npx nx run docker:docker:down

​
Services

​
Core Databases

ServicePortDescription
postgres5432PostgreSQL database (user: postgres, pass: postgres)
mongo27017MongoDB for document storage
redis6379Redis for caching and task queue
chromadb8080:8000Vector database for embeddings
rabbitmq5672, 15672Message broker (AMQP + Management UI)

​
Application Services (Profile-based)

ServiceProfileDescription
gaia-backendbackend, allFastAPI application on port 8000
arq_workerworker, allBackground job processor

​
Development Tools

ServicePortDescription
mongo_express8081MongoDB web UI (admin/password)

​
Profiles

Docker profiles allow running specific service groups:

​
Default (No Profile)

Runs only infrastructure services (databases, queues): 
docker compose -f infra/docker/docker-compose.yml up -d

​
Backend Profile

Adds the FastAPI application to infrastructure: 
docker compose -f infra/docker/docker-compose.yml --profile backend up -d

​
All Profile

Runs everything including workers: 
docker compose -f infra/docker/docker-compose.yml --profile all up -d
For development, we recommend running databases in Docker and the API/web locally with mise for faster hot-reloading.

​
Production Setup

For production, use docker-compose.prod.yml: 
docker compose -f infra/docker/docker-compose.prod.yml up -d
Key differences:
  • Uses pre-built images from GHCR
  • No volume mounts for source code
  • Optimized for stability over development speed

​
Data Persistence

Named volumes preserve data across restarts:
VolumePurpose
chroma_dataVector embeddings
pgdataPostgreSQL data
redis_dataRedis cache
mongo_dataMongoDB documents
rabbitmq_dataMessage queue state

​
Reset All Data

docker compose -f infra/docker/docker-compose.yml down -v
This deletes all local data including the database. Use with caution.

​
Health Checks

All services include health checks:
  • Databases: Connection/ping tests
  • Backend: HTTP /health endpoint
  • RabbitMQ: rabbitmqctl status
Check service health: 
docker compose -f infra/docker/docker-compose.yml ps

​
Common Commands

# View logs for specific service
docker compose -f infra/docker/docker-compose.yml logs -f postgres

# Rebuild a service
docker compose -f infra/docker/docker-compose.yml build gaia-backend

# Restart a single service
docker compose -f infra/docker/docker-compose.yml restart redis

# Execute command in container
docker compose -f infra/docker/docker-compose.yml exec mongo mongosh

​
Troubleshooting

Another service is using the port. Stop it or change the port mapping in docker-compose.yml: bash lsof -i :8000 # Find what's using port 8000
Check logs for the failing service: bash docker compose -f infra/docker/docker-compose.yml logs postgres
Ensure containers are healthy: bash docker compose -f infra/docker/docker-compose.yml ps Wait for healthy status before connecting.

​
See Also