Docker Compose Setup

Local development and testing with Docker Compose.

Not for Production

Docker Compose is designed for local development and testing only. For production deployments, use the Kubernetes deployment guide instead.

Overview

Aurora provides two Docker Compose configurations:

File	Use Case
docker-compose.yaml	Local development with hot-reload
docker-compose.prod-local.yml	Testing production builds locally

Development Setup

Prerequisites

• Docker 24.0+ and Docker Compose v2
• 8GB+ RAM (16GB recommended)
• LLM API key (OpenRouter, OpenAI, or Anthropic)

1. Clone and Configure

git clone https://github.com/arvo-ai/aurora.git
cd aurora

# Initialize configuration (generates .env with random secrets)
make init

2. Configure Environment

Edit .env and add your LLM API key:

# Required: At least one LLM API key
OPENROUTER_API_KEY=sk-or-v1-your-key
# OR
OPENAI_API_KEY=sk-your-openai-key
# OR
ANTHROPIC_API_KEY=sk-ant-your-key

Other values are auto-generated by make init. See the environment variables guide for all options.

3. Start Development Stack

make dev

This starts all services with hot-reload enabled for the frontend and backend.

4. Configure Vault Token

After first startup, get the Vault token:

# Get root token
docker logs vault-init 2>&1 | grep "Root Token:"

# Add to .env
echo "VAULT_TOKEN=hvs.xxxxx" >> .env

# Restart
make down && make dev

Development Commands

Command	Description
make dev	Start development stack with hot-reload
make down	Stop all services
make logs	View logs (last 50 lines, follows)
make rebuild-server	Rebuild API server only
make clean	Stop and remove volumes

Testing Production Builds Locally

To test production builds without deploying to Kubernetes:

# Option A: Pull prebuilt images from GHCR (fastest)
make prod-prebuilt   # or: make prod-local to build from source

# Option B: Build from source and start
make prod-local

# View logs
make prod-logs

# Stop
make down

This uses docker-compose.prod-local.yml which runs optimized production images on your local machine.

Shorthand Commands

make prod is an alias for make prod-prebuilt. make prod-build is an alias for make prod-local.

Accessing Aurora

Once the services are running:

• Frontend: http://localhost:3000
• API: http://localhost:5080
• WebSocket: ws://localhost:5006
• SeaweedFS UI: http://localhost:8888 (file browser)

Remote / VM Access

If Aurora is running on a remote server or VM, update the URL variables in .env to point to the machine's IP (or hostname):

FRONTEND_URL=http://YOUR_IP:3000
NEXT_PUBLIC_BACKEND_URL=http://YOUR_IP:5080
NEXT_PUBLIC_WEBSOCKET_URL=ws://YOUR_IP:5006

Then recreate the frontend container to pick up the new values (no rebuild needed):

docker compose -f docker-compose.prod-local.yml up -d frontend

Make sure the relevant ports (3000, 5080, 5006) are open in your firewall or cloud security group.

Service Architecture

All services run in Docker containers:

    ┌─────────┐         ┌─────────┐         ┌─────────┐
    │Frontend │         │  API    │         │ Chatbot │
    │  :3000  │         │ :5080   │         │  :5006  │
    └─────────┘         └─────────┘         └─────────┘
                              │
                              ▼
                     ┌─────────────────┐
                     │  Celery Worker  │
                     │ (background)    │
                     └─────────────────┘
                              │
    ┌─────────────────────────┼─────────────────────────┐
    │           │             │             │           │
    ▼           ▼             ▼             ▼           ▼
┌───────┐ ┌─────────┐ ┌──────────┐ ┌───────┐ ┌─────────┐
│Postgres│ │  Redis  │ │ Weaviate │ │ Vault │ │SeaweedFS│
│ :5432  │ │  :6379  │ │  :8080   │ │ :8200 │ │  :8333  │
└───────┘ └─────────┘ └──────────┘ └───────┘ └─────────┘

Data Persistence

Data is stored in Docker volumes and persists across container restarts:

Volume	Contains
aurora_postgres_data	PostgreSQL database
aurora_redis_data	Redis data
aurora_weaviate_data	Vector embeddings
aurora_vault_data	Vault secrets
aurora_seaweedfs_data	Object storage

To remove all data and start fresh:

make clean              # for dev
make prod-clean

Monitoring

Health Checks

# API health
curl http://localhost:5080/health

# Vault health
curl http://localhost:8200/v1/sys/health

# Check all services
docker compose ps

Logs

# All logs (last 50 lines, follows)
make logs

# Specific service
docker compose logs -f aurora-server

# Production build logs
make prod-logs

Troubleshooting

Services Won't Start

# Check status
docker compose ps

# Check specific service logs
docker logs aurora-server

# Verify required env vars are set
cat .env | grep -E "^(OPENROUTER_API_KEY|VAULT_TOKEN)"

Database Connection Issues

# Check postgres is running
docker exec aurora-postgres-1 pg_isready

# Test connection
docker exec aurora-postgres-1 psql -U aurora -d aurora_db -c "SELECT 1"

Vault Sealed After Restart

Vault requires manual unsealing after container restarts:

# Get unseal key from vault-init logs
docker logs vault-init 2>&1 | grep "Unseal Key"

# Unseal Vault
docker exec -it aurora-vault-1 vault operator unseal <UNSEAL_KEY>

Out of Disk Space

# Check disk usage
docker system df

# Clean unused images
docker image prune -a

# Clean build cache
docker builder prune

Port Already in Use

If ports 3000, 5080, or 5006 are already in use:

# Find what's using the port
lsof -i :3000

# Either stop that service or change Aurora's ports in docker-compose.yaml

Next Steps

• Production deployment: See the Kubernetes deployment guide for production-ready deployments with high availability
• Configuration: Review all environment variables for customization options
• Integrations: Connect to cloud providers and observability tools in the integrations guide
• Development: See the development setup guide for contributing to Aurora