> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heygaia.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Docker

> Understanding GAIA's Docker setup, services, and how it integrates with mise and Nx

## 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.

<Note>
  Docker files are located in `infra/docker/`. The setup uses Nx to manage
  Docker as a project with its own targets.
</Note>

***

## Quick Start

### Recommended: Use mise

```bash theme={null}
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:

```bash theme={null}
# 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

```bash theme={null}
# 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):

```bash theme={null}
docker compose -f infra/docker/docker-compose.yml up -d
```

### Backend Profile

Adds the FastAPI application to infrastructure:

```bash theme={null}
docker compose -f infra/docker/docker-compose.yml --profile backend up -d
```

### All Profile

Runs everything including workers:

```bash theme={null}
docker compose -f infra/docker/docker-compose.yml --profile all up -d
```

<Tip>
  For development, we recommend running databases in Docker and the API/web
  locally with mise for faster hot-reloading.
</Tip>

***

## Production Setup

For production, use `docker-compose.prod.yml`:

```bash theme={null}
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

```bash theme={null}
docker compose -f infra/docker/docker-compose.yml down -v
```

<Warning>
  This deletes all local data including the database. Use with caution.
</Warning>

***

## Health Checks

All services include health checks:

* **Databases**: Connection/ping tests
* **Backend**: HTTP `/health` endpoint
* **RabbitMQ**: `rabbitmqctl status`

Check service health:

```bash theme={null}
docker compose -f infra/docker/docker-compose.yml ps
```

***

## Common Commands

```bash theme={null}
# 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

<AccordionGroup>
  <Accordion title="Port already in use">
    Another service is using the port. Stop it or change the port mapping in
    docker-compose.yml:

    ```bash theme={null}
    lsof -i :8000 # Find what's using port 8000
    ```
  </Accordion>

  <Accordion title="Container won't start">
    Check logs for the failing service:

    ```bash theme={null}
    docker compose -f infra/docker/docker-compose.yml logs postgres
    ```
  </Accordion>

  <Accordion title="Database connection refused">
    Ensure containers are healthy:

    ```bash theme={null}
    docker compose -f infra/docker/docker-compose.yml ps
    ```

    Wait for `healthy` status before connecting.
  </Accordion>
</AccordionGroup>

***

## See Also

* [Development Setup](/developers/development-setup)
* [Commands Reference](/developers/commands)