Docker

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

Recommended: Use mise

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

Service	Port	Description
postgres	`5432`	PostgreSQL database (user: `postgres`, pass: `postgres`)
mongo	`27017`	MongoDB for document storage
redis	`6379`	Redis for caching and task queue
chromadb	`8080:8000`	Vector database for embeddings
rabbitmq	`5672`, `15672`	Message broker (AMQP + Management UI)

Application Services (Profile-based)

Service	Profile	Description
gaia-backend	`backend`, `all`	FastAPI application on port 8000
arq_worker	`worker`, `all`	Background job processor

Development Tools

Service	Port	Description
mongo_express	`8081`	MongoDB 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:

Volume	Purpose
`chroma_data`	Vector embeddings
`pgdata`	PostgreSQL data
`redis_data`	Redis cache
`mongo_data`	MongoDB documents
`rabbitmq_data`	Message 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

Port already in use

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

Container won't start

Check logs for the failing service:

docker compose -f infra/docker/docker-compose.yml logs postgres

Database connection refused

Ensure containers are healthy:

docker compose -f infra/docker/docker-compose.yml ps

Wait for healthy status before connecting.

Getting Started

Self-Hosting

CLI

Contributing

Bot Development

Conventions

Overview

Quick Start

Recommended: Use mise

Manual Docker Control

Using Nx Docker Commands

Services

Core Databases

Application Services (Profile-based)

Development Tools

Profiles

Default (No Profile)

Backend Profile

All Profile

Production Setup

Data Persistence

Reset All Data

Health Checks

Common Commands

Troubleshooting

See Also

​Overview

​Quick Start

​Recommended: Use mise

​Manual Docker Control

​Using Nx Docker Commands

​Services

​Core Databases

​Application Services (Profile-based)

​Development Tools

​Profiles

​Default (No Profile)

​Backend Profile

​All Profile

​Production Setup

​Data Persistence

​Reset All Data

​Health Checks

​Common Commands

​Troubleshooting

​See Also

Overview

Quick Start

Recommended: Use mise

Manual Docker Control

Using Nx Docker Commands

Services

Core Databases

Application Services (Profile-based)

Development Tools

Profiles

Default (No Profile)

Backend Profile

All Profile

Production Setup

Data Persistence

Reset All Data

Health Checks

Common Commands

Troubleshooting

See Also