Skip to main content

​
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:
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:Additional UIs:

​
Architecture

The Docker Compose stack includes:
ServiceDescriptionPort
frontendNext.js web UI3000
aurora-serverFlask REST API5080
chatbotWebSocket chatbot service5006
celery_workerBackground task workers-
celery_beatTask scheduler-
postgresPostgreSQL database5432
redisTask queue & cache6379
weaviateVector database8080
t2v-transformersML embeddings service-
vaultHashiCorp Vault secrets8200
seaweedfs-masterObject storage master9333
seaweedfs-volumeObject storage volume8081
seaweedfs-filerS3-compatible API8333, 8888
memgraphGraph database7687
memgraph-labGraph visualization3001
searxngWeb search engine8082

​
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

Build docs developers (and LLMs) love

Get started for freeTalk to us