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:
lsof -i :8000 # Find what's using port 8000
Check logs for the failing service:
docker compose -f infra/docker/docker-compose.yml logs postgres
Ensure containers are healthy:
docker compose -f infra/docker/docker-compose.yml ps
Wait for healthy status before connecting.

​
See Also