​
Docker Deployment Guide

GAIA uses Docker Compose to orchestrate all the required services. This makes deployment simple and ensures consistency across different environments.

​
Prerequisites

​
Project Structure

gaia/
├── docker-compose.yml          # Main compose file
├── docker-compose.prod.yml     # Production overrides
├── backend/
│   ├── Dockerfile
│   ├── .env                    # Backend environment variables
│   └── ...
├── frontend/
│   ├── Dockerfile
│   ├── .env                    # Frontend environment variables
│   └── ...
└── docs/

​
Quick Start

1

Clone and Navigate

git clone https://github.com/heygaia/gaia.git
cd gaia
2

Configure Environment

See the Environment Variables guide for details.
3

Start All Services

# Start in detached mode (background)
 docker compose up -d
# Or start with logs visible
 docker compose up
4

Verify Deployment

Check that all services are running:
docker compose ps
Access the applications:

​
Service Overview

The Docker Compose setup includes the following services:

​
Docker Commands

​
Starting and Stopping

# Start all services
docker compose up -d

# Start specific services
docker compose up -d gaia-backend postgres redis

# Stop all services
docker compose down

# Stop and remove volumes (⚠️ deletes data)
docker compose down -v

​
Viewing Logs

# View logs for all services
docker compose logs -f

# View logs for specific service
docker compose logs -f gaia-backend

# View logs with timestamps
docker compose logs -f -t

# View last 100 lines
docker compose logs --tail=100 gaia-backend

​
Service Management

# Restart a service
docker compose restart gaia-backend

# Rebuild and restart a service
docker compose up -d --build gaia-backend

# Execute commands in running container
docker compose exec gaia-backend bash
docker compose exec postgres psql -U postgres -d langgraph

# Check service status
docker compose ps

​
Development Mode

For development, use the default docker-compose.yml: 
# Start with hot reload
docker compose up -d

# View real-time logs
docker compose logs -f gaia-backend frontend
Development Features:
  • Hot reload for both frontend and backend
  • Source code mounted as volumes
  • Debug logging enabled
  • Development databases with default credentials

​
Health Checks

All services include health checks. Monitor service health: 
# Check health status
docker compose ps

# Services with health checks:
# ✓ gaia-backend - HTTP health endpoint
# ✓ postgres - pg_isready
# ✓ redis - redis-cli ping
# ✓ mongo - mongosh ping
# ✓ chromadb - TCP connection check
# ✓ rabbitmq - rabbitmqctl status

​
Data Persistence

Data is persisted using Docker volumes: 
# View volumes
docker volume ls | grep gaia

# Backup a volume
docker run --rm -v gaia-dev_pgdata:/data -v $(pwd):/backup alpine tar czf /backup/postgres-backup.tar.gz -C /data .

# Restore a volume
docker run --rm -v gaia-dev_pgdata:/data -v $(pwd):/backup alpine tar xzf /backup/postgres-backup.tar.gz -C /data
Volume Locations:
  • pgdata - PostgreSQL data
  • mongo_data - MongoDB data
  • redis_data - Redis data
  • chroma_data - ChromaDB vectors
  • rabbitmq_data - RabbitMQ messages

​
Networking

Services communicate through the gaia_network bridge network: 
# Inspect network
docker network inspect gaia-dev_gaia_network

# Services can reach each other by container name:
# - gaia-backend → postgres:5432
# - gaia-backend → redis:6379
# - gaia-backend → chromadb:8000

​
Next Steps

Environment Variables

Configure your API keys and settings

Infisical Setup

Secure secret management