Docker for development

In development, Docker runs only the services GAIA depends on: databases, queues and a few helpers. Your code (API, web, bots) runs natively through mise, so it hot-reloads. Every mise dev* command starts these services for you, so you rarely touch Docker directly. Running GAIA for real rather than developing it? Self-Hosting uses a different, self-contained compose file that gaia up manages. The compose file is infra/docker/docker-compose.yml. Nx wraps it as the docker project:

nx run docker:docker:up     # start the default services (what mise dev runs)
nx run docker:docker:down   # stop and remove them; data is kept

Default services

docker compose up with no profile starts these:

Service	Host port	Purpose
`mongo`	27017	MongoDB, most app data
`postgres`	5432	PostgreSQL (user `postgres`, password `postgres`): agent checkpoints and the memory graph
`redis`	6379	Cache and the ARQ job queue
`chromadb`	8080	Vector search
`rabbitmq`	5672, 15672	Message broker, plus its management UI on 15672
`jfs-meta-redis`	6380	Metadata store for JuiceFS workspace files (used by `mise dev:vm`)
`mongo_express`	8083	Browse MongoDB in the browser (user `admin`, password `password`)
`searxng`	8888	Local web search engine used by the search tools

Each host port can be moved with an environment variable named after it, for example MONGO_HOST_PORT=27018. The variable names are in the ports: lines of the compose file.

Profiles

A profile is a named group of extra services that only start when you ask for it with --profile:

Profile	Adds	When you need it
`backend`	The API in a container, plus the embedding sidecar, browser hosts and voice worker	`mise dev:vm` uses this. You rarely start it by hand
`worker`	The ARQ worker in a container, plus the embedding sidecar and browser hosts	Testing the worker as it runs in production
`bots`	All five bots in containers	Running bots without the source toolchain
`voice`	The voice agent worker	Voice work without `mise dev:full`
`observability`	Loki, Promtail and Grafana	See Debugging and logs: their configuration is not in this repository
`all`	Everything above except the voice worker	Rarely useful in development

docker compose -f infra/docker/docker-compose.yml --profile worker up -d

Inspect and reset

docker compose -f infra/docker/docker-compose.yml ps             # status and health
docker compose -f infra/docker/docker-compose.yml logs -f mongo   # follow one service's logs
docker compose -f infra/docker/docker-compose.yml exec mongo mongosh   # a MongoDB shell

Data lives in named Docker volumes (mongo_data, pgdata, redis_data, chroma_data, rabbitmq_data and others), so it survives docker:down and restarts. To start from empty databases:

docker compose -f infra/docker/docker-compose.yml down -v

down -v deletes every local database, including your development user. Run mise seed again afterwards.

Troubleshooting

A port is already in use

Find what holds it with lsof -i :27017 (use the port from the error). Stop that process, or move GAIA’s port with its environment variable, for example MONGO_HOST_PORT=27018, and update the matching URL in apps/api/.env.

A container keeps restarting

Read its logs: docker compose -f infra/docker/docker-compose.yml logs <service>.

The API can't connect to a database

Run docker compose -f infra/docker/docker-compose.yml ps and wait until the service shows healthy.

Start here

Everyday work

Go deeper

Reference

Default services

Profiles

Inspect and reset

Troubleshooting