> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/Arvo-AI/aurora/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Steps>
  <Step title="Clone the repository">
    ```bash theme={null}
    git clone https://github.com/Arvo-AI/aurora.git
    cd aurora
    ```
  </Step>

  <Step title="Initialize environment">
    Run the initialization script to generate secure secrets:

    ```bash theme={null}
    make init
    ```

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

    * `POSTGRES_PASSWORD`
    * `FLASK_SECRET_KEY`
    * `AUTH_SECRET`
    * `SEARXNG_SECRET`
  </Step>

  <Step title="Configure LLM API key">
    Edit `.env` and add at least one LLM API key:

    ```bash theme={null}
    # 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](https://openrouter.ai/keys) (recommended, supports multiple models)
    * OpenAI: [https://platform.openai.com/api-keys](https://platform.openai.com/api-keys)
    * Anthropic: [https://console.anthropic.com/](https://console.anthropic.com/)
    * Google AI: [https://makersuite.google.com/app/apikey](https://makersuite.google.com/app/apikey)
  </Step>

  <Step title="Start Aurora">
    For development:

    ```bash theme={null}
    make dev
    ```

    For production-like deployment (prebuilt images):

    ```bash theme={null}
    make prod-prebuilt
    ```

    Or build from source:

    ```bash theme={null}
    make prod-local
    ```
  </Step>

  <Step title="Access the UI">
    Wait 30-60 seconds for services to start, then open:

    * **Frontend**: [http://localhost:3000](http://localhost:3000)
    * **Backend API**: [http://localhost:5080](http://localhost:5080)
    * **WebSocket**: ws\://localhost:5006

    Additional UIs:

    * **Vault**: [http://localhost:8200](http://localhost:8200)
    * **Weaviate**: [http://localhost:8080](http://localhost:8080)
    * **SeaweedFS**: [http://localhost:8888](http://localhost:8888)
    * **Memgraph Lab**: [http://localhost:3001](http://localhost:3001)
  </Step>
</Steps>

## 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

```bash theme={null}
# 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

```bash theme={null}
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

```bash theme={null}
# 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:

```bash theme={null}
# 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

```bash theme={null}
VAULT_ADDR=http://vault:8200
VAULT_TOKEN=<generated-on-first-run>
VAULT_KV_MOUNT=aurora
```

On first startup, get the Vault token:

```bash theme={null}
docker logs aurora-vault-init
```

Copy the root token and add it to `.env`.

## Common Operations

### View Logs

```bash theme={null}
# All services
make logs

# Specific service
make logs aurora-server
make logs celery_worker
```

### Restart Services

```bash theme={null}
# Restart all
make restart

# Rebuild and restart specific service
make rebuild-server
```

### Stop Services

```bash theme={null}
make down
```

### Clean Up

```bash theme={null}
# Stop and remove volumes
make clean

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

### Fresh Rebuild

```bash theme={null}
# 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:
  ```bash theme={null}
  VERSION=v1.2.3 make prod-prebuilt
  ```

## Troubleshooting

### Services Not Starting

Check if `.env` exists:

```bash theme={null}
ls -la .env
```

If missing, run:

```bash theme={null}
make init
```

### Port Conflicts

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

```bash theme={null}
FLASK_PORT=5080  # Backend API
# Frontend is always :3000 (edit docker-compose.yaml ports section)
```

### Database Connection Errors

Check Postgres is healthy:

```bash theme={null}
docker logs aurora-postgres
```

Reset database:

```bash theme={null}
make clean
make dev
```

### Vault Not Initialized

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

```bash theme={null}
docker logs aurora-vault-init
```

Add to `.env`:

```bash theme={null}
VAULT_TOKEN=hvs.xxx...
```

Restart services:

```bash theme={null}
make restart
```

### SeaweedFS Bucket Missing

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

```bash theme={null}
docker logs aurora-seaweedfs-init
```

Manually create:

```bash theme={null}
docker exec -it aurora-seaweedfs-filer sh
weed shell
> s3.bucket.create -name aurora-storage
```

### Out of Memory

Reduce resource usage by limiting services:

```yaml theme={null}
# In docker-compose.yaml, comment out optional services:
# - memgraph-lab
# - searxng
```

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

## Updating

### Update to Latest

```bash theme={null}
git pull origin main
make down
make dev  # or make prod-prebuilt
```

### Update Single Service

```bash theme={null}
# 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:

```bash theme={null}
docker run --rm -v aurora_postgres-data:/data -v $(pwd):/backup \
  alpine tar czf /backup/postgres-backup.tar.gz /data
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Production Deployment" icon="server" href="/deployment/production-considerations">
    Best practices for production deployments
  </Card>

  <Card title="Kubernetes Deployment" icon="dharmachakra" href="/deployment/kubernetes">
    Deploy Aurora on Kubernetes
  </Card>

  <Card title="Scaling" icon="chart-line" href="/deployment/scaling">
    Scale Aurora for high availability
  </Card>

  <Card title="Configuration" icon="gear" href="/configuration/environment-variables">
    Complete environment variable reference
  </Card>
</CardGroup>