​
Who This Guide Is For

This development setup guide is designed for:

Contributors

Developers who want to contribute to the GAIA project by fixing bugs, adding features, or improving documentation

Customizers

Developers who want to modify GAIA for their specific use cases or integrate it with custom systems

Open Source Enthusiasts

Developers who want to learn from the codebase, understand the architecture, or build upon GAIA

Enterprise Teams

Development teams who need to customize GAIA for enterprise deployment and integration

​
Prerequisites

Before you begin, ensure you have the following installed:

​
Development Environment Setup

To start developing on GAIA, you need to set up your local environment. You can choose between an automated setup using our script or a manual setup.

Automated Setup

The easiest way to get started. Our script handles everything for you.

Manual Setup

For those who want more control over the setup process.

​
Automated Setup

We provide a script that automates the entire setup process. This is the recommended method for most users.

1

Run the Setup Script

Open your terminal and run the following command from the project root:

./scripts/setup.sh

This script will:

  • Start the required services with Docker Compose.
  • Create a Python virtual environment.
  • Install backend dependencies with uv.
  • Install frontend dependencies with pnpm.
2

You're Ready!

Once the script finishes, your development environment is ready to go!

​
Manual Setup

If you prefer to set up your environment manually, follow these steps.

​
Environment Variables

Before you start the services, you need to configure your environment variables. GAIA uses .env files to manage these settings.

1

Copy Example Files

We provide example files to get you started. Copy them to create your own .env files:

cp backend/.env.example backend/.env
cp frontend/.env.example frontend/.env
2

Fill in Your Secrets

Edit the newly created .env files and fill in your API keys and other secrets.

For a detailed explanation of all the available environment variables, see the Environment Variables Reference.

​
Backend Setup

1

Start Docker Services

GAIA relies on several services that run in Docker containers. You have two options:

Option 1: Start all services (including frontend in Docker)

docker-compose up -d

Option 2: Start only backend services (recommended for development)

docker compose --profile backend-only up -d

Why use backend-only profile?

Running the frontend in Docker can introduce slight latency and slower hot reloading. For the best development experience, we recommend using the backend-only profile and running the frontend manually with pnpm dev (see Frontend Setup below).

2

Create Virtual Environment

Create and activate a Python virtual environment:

python3 -m venv .venv
source .venv/bin/activate
3

Install Backend Dependencies

We use uv for fast dependency management. Install the required packages:

uv pip install -r backend/requirements.txt

​
Frontend Setup

1

Navigate to Frontend Directory

cd frontend
2

Install Frontend Dependencies

We use pnpm for managing frontend packages. Install them with:

pnpm install
3

Start Development Server (Recommended)

For the best development experience with fast hot reloading, run the frontend manually:

pnpm dev

This will start the Next.js development server on http://localhost:3000 with optimized hot reloading.

Performance Tip: Running the frontend outside Docker provides faster hot reloading and better performance during development. The frontend will automatically connect to the backend services running in Docker.

4

Return to Root Directory

cd ..

​
Running the Development Environment

After completing the setup, here’s how to start your development environment:

1

Start Backend Services

Start only the backend services and databases using the backend-only profile:

docker compose --profile backend-only up -d

This starts:

  • gaia-backend - FastAPI application (port 8000)
  • postgres - Database (port 5432)
  • redis - Cache & sessions (port 6379)
  • mongo - Document storage (port 27017)
  • chromadb - Vector database (port 8080)
  • rabbitmq - Message queue (port 5672, management UI on 15672)
  • arq_worker - Background task worker
  • worker - Scheduler worker
2

Start Frontend Development Server

In a separate terminal, navigate to the frontend directory and start the development server:

cd frontend
pnpm dev

The frontend will be available at http://localhost:3000 with optimized hot reloading.

3

Verify Setup

​
Alternative: Full Docker Setup

If you prefer to run everything in Docker (including the frontend):

docker compose up -d

Performance Note: This approach may result in slower hot reloading for frontend development compared to running the frontend manually with pnpm dev.

​
Stopping Services

To stop all running Docker services:

docker compose down

To stop and remove all data (reset everything):

docker compose down -v