Skip to main content

​
Docker Deployment Guide

GAIA uses Docker Compose to orchestrate all the required services. This makes deployment simple and ensures consistency across different environments.
Looking for an easier setup? The GAIA CLI provides a guided wizard that handles Docker setup automatically, including prerequisite checks, environment variable discovery, and service management. This guide covers manual Docker setup for advanced users who prefer full control.

​
Prerequisites

Install Docker Desktop (recommended for beginners):Or install Docker Engine (for servers):
# Ubuntu/Debian (example)
sudo apt-get update
sudo apt-get install -y docker.io docker-compose-plugin
sudo systemctl enable --now docker

# Add user to docker group
sudo usermod -aG docker $USER
newgrp docker
Minimum Requirements:
  • 2 CPU cores
  • 4GB RAM
  • 10GB free disk space
  • Docker Engine 20.10+
  • Docker Compose v2.0+
Recommended for Production:
  • 4+ CPU cores
  • 8+ GB RAM
  • 50+ GB SSD storage
  • Regular backups configured

​
Project Structure

When using the CLI quick start, running gaia init with Self-Host (Docker) scaffolds this structure automatically.
gaia/
├── apps/
│   ├── api/
│   │   ├── Dockerfile
│   │   ├── .env                # API environment variables
│   │   └── ...
│   ├── web/
│   │   ├── Dockerfile
│   │   ├── .env                # Web environment variables
│   │   └── ...
├── docs/
├── infra/
│   └── docker/
│       ├── docker-compose.yml      # Development compose file
│       └── docker-compose.prod.yml # Production compose file
└── ...

​
Quick Start

1

Install CLI and initialize self-host mode

npm install -g @heygaia/cli

gaia init
Choose Self-Host (Docker) in the setup wizard.
2

Start the stack

gaia start
3

Verify and monitor

gaia status
gaia logs
Access the applications:

​
Service Overview

The Docker Compose setup includes the following services:
Next.js React Application
  • Port: 3000
  • Hot reload enabled in development
  • Serves the web interface
web:
  container_name: gaia-web
  build: ./apps/web
  ports:
    - "3000:3000"
  environment:
    - NEXT_PUBLIC_API_BASE_URL=http://localhost:8000
FastAPI Python Application
  • Port: 8000
  • Auto-reload enabled in development
  • RESTful API and WebSocket support
gaia-backend:
  container_name: gaia-backend
  build: ./apps/api
  ports:
    - "8000:80"
  command: ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--reload"]
PostgreSQL (Port: 5432)
  • Stores user data and application state
  • User: postgres, Password: postgres, DB: langgraph
MongoDB (Port: 27017)
  • Document storage and metadata
  • No authentication in development
Redis (Port: 6379)
  • Caching and session storage
  • No authentication in development
ChromaDB (Port: 8080)
  • Vector database for embeddings
  • Persistent storage in Docker volume
Worker - Handles scheduled tasks and background processing ARQ Worker - Async task queue processing RabbitMQ - Message broker (Port: 5672, Management: 15672)

​
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

​
Alternative: CLI Setup

For a simplified setup experience with automatic configuration, see the CLI Setup Guide. The CLI handles all the Docker commands, environment setup, and health checks automatically.

​
Next Steps

Environment Variables

Configure your API keys and settings