Docker Compose Deployment

Deploy Aurora using Docker Compose for development and local testing

Docker Compose Deployment

Deploy Aurora locally using Docker Compose for development, testing, or small-scale production use.

Prerequisites

• Docker Engine 20.10 or newer
• Docker Compose v2.0 or newer
• 8GB RAM minimum (16GB recommended)
• 20GB free disk space

Quick Start

1. Clone the repository

   git clone https://github.com/Arvo-AI/aurora.git
   cd aurora
   
2. Initialize environment

   Run the initialization script to generate secure secrets:

   make init
   

   This creates a .env file from .env.example and generates:

   • POSTGRES_PASSWORD
   • FLASK_SECRET_KEY
   • AUTH_SECRET
   • SEARXNG_SECRET
3. Configure LLM API key

   Edit .env and add at least one LLM API key:

   # Required - choose at least one:
   OPENROUTER_API_KEY=sk-or-v1-...
   # OR
   OPENAI_API_KEY=sk-...
   # OR
   ANTHROPIC_API_KEY=sk-ant-...
   # OR
   GOOGLE_AI_API_KEY=...
   

   Get API keys from:

   • OpenRouter: https://openrouter.ai/keys (recommended, supports multiple models)
   • OpenAI: https://platform.openai.com/api-keys
   • Anthropic: https://console.anthropic.com/
   • Google AI: https://makersuite.google.com/app/apikey
4. Start Aurora

   For development:

   make dev
   

   For production-like deployment (prebuilt images):

   make prod-prebuilt
   

   Or build from source:

   make prod-local
   
5. Access the UI

   Wait 30-60 seconds for services to start, then open:

   • Frontend: http://localhost:3000
   • Backend API: http://localhost:5080
   • WebSocket: ws://localhost:5006

   Additional UIs:

   • Vault: http://localhost:8200
   • Weaviate: http://localhost:8080
   • SeaweedFS: http://localhost:8888
   • Memgraph Lab: http://localhost:3001

Architecture

The Docker Compose stack includes:

Service	Description	Port
frontend	Next.js web UI	3000
aurora-server	Flask REST API	5080
chatbot	WebSocket chatbot service	5006
celery_worker	Background task workers	-
celery_beat	Task scheduler	-
postgres	PostgreSQL database	5432
redis	Task queue & cache	6379
weaviate	Vector database	8080
t2v-transformers	ML embeddings service	-
vault	HashiCorp Vault secrets	8200
seaweedfs-master	Object storage master	9333
seaweedfs-volume	Object storage volume	8081
seaweedfs-filer	S3-compatible API	8333, 8888
memgraph	Graph database	7687
memgraph-lab	Graph visualization	3001
searxng	Web search engine	8082

Configuration

Environment Variables

Key configuration options in .env:

Required

# Database
POSTGRES_USER=aurora
POSTGRES_PASSWORD=<generated-by-make-init>
POSTGRES_DB=aurora_db

# Security
FLASK_SECRET_KEY=<generated-by-make-init>
AUTH_SECRET=<generated-by-make-init>

# LLM API (at least one required)
OPENROUTER_API_KEY=sk-or-v1-...
LLM_PROVIDER_MODE=openrouter

URLs

FRONTEND_URL=http://localhost:3000
BACKEND_URL=http://aurora-server:5080
NEXT_PUBLIC_BACKEND_URL=http://localhost:5080
NEXT_PUBLIC_WEBSOCKET_URL=ws://localhost:5006

Object Storage

# Default: SeaweedFS (included in docker-compose)
STORAGE_BUCKET=aurora-storage
STORAGE_ENDPOINT_URL=http://seaweedfs-filer:8333
STORAGE_ACCESS_KEY=admin
STORAGE_SECRET_KEY=admin
STORAGE_REGION=us-east-1
STORAGE_USE_SSL=false

For production, use external S3-compatible storage:

# AWS S3
STORAGE_ENDPOINT_URL=https://s3.amazonaws.com
STORAGE_ACCESS_KEY=<your-aws-key>
STORAGE_SECRET_KEY=<your-aws-secret>
STORAGE_USE_SSL=true

Vault

VAULT_ADDR=http://vault:8200
VAULT_TOKEN=<generated-on-first-run>
VAULT_KV_MOUNT=aurora

On first startup, get the Vault token:

docker logs aurora-vault-init

Copy the root token and add it to .env.

Common Operations

View Logs

# All services
make logs

# Specific service
make logs aurora-server
make logs celery_worker

Restart Services

# Restart all
make restart

# Rebuild and restart specific service
make rebuild-server

Stop Services

make down

Clean Up

# Stop and remove volumes
make clean

# Full cleanup (containers, volumes, images)
make nuke

Fresh Rebuild

# Development
make dev-fresh

# Production
make prod-fresh

Development vs Production

Development Mode (make dev)

• Uses docker-compose.yaml
• Hot reload enabled for code changes
• Source code mounted as volumes
• Debug logging enabled
• No build optimizations

Production Mode (make prod-local)

• Uses docker-compose.prod-local.yml
• Builds optimized production images
• No source code mounts
• Production logging
• Automatic restarts
• Health checks enabled

Prebuilt Images (make prod-prebuilt)

• Pulls images from GitHub Container Registry
• No build step required
• Use VERSION=v1.2.3 to pin a specific release:
  VERSION=v1.2.3 make prod-prebuilt
  

Troubleshooting

Services Not Starting

Check if .env exists:

ls -la .env

If missing, run:

make init

Port Conflicts

If ports are already in use, edit .env to change:

FLASK_PORT=5080  # Backend API
# Frontend is always :3000 (edit docker-compose.yaml ports section)

Database Connection Errors

Check Postgres is healthy:

docker logs aurora-postgres

Reset database:

make clean
make dev

Vault Not Initialized

On first run, Vault auto-initializes. Get the token:

docker logs aurora-vault-init

Add to .env:

VAULT_TOKEN=hvs.xxx...

Restart services:

make restart

SeaweedFS Bucket Missing

The aurora-storage bucket is auto-created. If missing:

docker logs aurora-seaweedfs-init

Manually create:

docker exec -it aurora-seaweedfs-filer sh
weed shell
> s3.bucket.create -name aurora-storage

Out of Memory

Reduce resource usage by limiting services:

# In docker-compose.yaml, comment out optional services:
# - memgraph-lab
# - searxng

Or increase Docker memory limit (Docker Desktop: Settings → Resources).

Updating

Update to Latest

git pull origin main
make down
make dev  # or make prod-prebuilt

Update Single Service

# Pull latest image
docker compose pull aurora-server

# Restart
docker compose up -d aurora-server

Data Persistence

Data is stored in Docker volumes:

• postgres-data - PostgreSQL database
• weaviate_data - Vector embeddings
• vault-data - Secrets storage
• vault-init - Vault initialization state
• seaweedfs_master_data - Object storage metadata
• seaweedfs_volume_data - Object storage files
• seaweedfs_filer_data - Object storage index
• memgraph-data - Graph database
• terraform-workdir - Terraform state files

Backup volumes:

docker run --rm -v aurora_postgres-data:/data -v $(pwd):/backup \
  alpine tar czf /backup/postgres-backup.tar.gz /data

Next Steps

Production Deployment

Best practices for production deployments

Kubernetes Deployment

Deploy Aurora on Kubernetes

Scaling

Scale Aurora for high availability

Configuration

Complete environment variable reference