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.

​
Prerequisites

Install Docker Desktop (recommended for beginners):Or install Docker Engine (for servers):
# Ubuntu/Debian
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# 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

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:
Next.js React Application
  • Port: 3000
  • Hot reload enabled in development
  • Serves the web interface
frontend:
  container_name: gaia-frontend
  build: ./frontend
  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 yaml gaia-backend: container_name: gaia-backend build: ./backend 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

​
Next Steps

Environment Variables

Configure your API keys and settings

Infisical Setup

Secure secret management
⌘I