Development Environment Setup

Set up your local development environment for Aurora

Prerequisites

Before you begin, ensure you have the following installed:

• Docker and Docker Compose >= 28.x
• Node.js >= 18.x (for frontend development)
• Python >= 3.11 (for backend development)
• Make (for using Makefile commands)
• Git for version control

Initial Setup

1. Fork and Clone the Repository

First, fork the Aurora repository to your GitHub account:

1. Go to https://github.com/Arvo-AI/aurora
2. Click the “Fork” button in the top right
3. This creates a copy under your GitHub account

Then clone your fork locally:

git clone https://github.com/YOUR-USERNAME/aurora.git
cd aurora

2. Add Upstream Remote

Add the upstream repository to keep your fork in sync:

git remote add upstream https://github.com/Arvo-AI/aurora.git

3. Initialize Configuration

Run the initialization script to generate secure secrets:

make init

This command:

• Creates .env from .env.example
• Generates secure passwords for PostgreSQL, Redis, and other services
• Sets up initial Vault configuration

4. Configure LLM API Key

Edit the .env file and add your LLM API key. Aurora supports multiple providers:

• OpenRouter: Get a key at https://openrouter.ai/keys
• Anthropic: Get a key at https://console.anthropic.com/settings/keys
• OpenAI: Get a key at https://platform.openai.com/api-keys

nano .env
# Add one of:
# OPENROUTER_API_KEY=sk-or-v1-...
# ANTHROPIC_API_KEY=sk-ant-...
# OPENAI_API_KEY=sk-...

5. Start Development Environment

Start all containers in development mode with hot reloading:

make dev

This command builds and starts:

• aurora-server (Flask API) on port 5080
• celery_worker (background tasks)
• chatbot (WebSocket) on port 5006
• frontend (Next.js) on port 3000
• postgres on port 5432
• weaviate (vector DB) on port 8080
• redis on port 6379
• vault (secrets) on port 8200
• seaweedfs (object storage) on port 8333

6. Configure Vault Token

On first startup, retrieve the Vault root token from the initialization logs:

docker logs vault-init 2>&1 | grep "Root Token:"

Copy the token value and add it to your .env file:

nano .env
# Add:
VAULT_TOKEN=hvs.xxxxxxxxxxxxxxxxxxxxxxxxxxxx

7. Restart Aurora

Restart the services to load the Vault token:

make down
make dev

Access the Application

Once all services are running, you can access:

• Frontend: http://localhost:3000
• REST API: http://localhost:5080
• Chatbot WebSocket: ws://localhost:5006
• Vault UI: http://localhost:8200
• SeaweedFS File Browser: http://localhost:8888
• SeaweedFS Cluster Status: http://localhost:9333

Development Workflow

Hot Reloading

Both frontend and backend support hot reloading in development mode:

• Backend: Flask auto-reloads when Python files change
• Frontend: Next.js with Turbopack provides instant updates

Viewing Logs

View logs for all containers:

make logs

View logs for a specific service:

make logs frontend
make logs aurora-server
make logs celery_worker

For detailed backend logs:

docker logs -f aurora-celery_worker-1

Stopping the Environment

Stop all containers:

make down

Rebuilding Services

Rebuild only the backend API:

make rebuild-server

Rebuild all containers:

make build

Clean Rebuild

For a complete fresh build without cache:

make dev-fresh

This command:

1. Stops all containers
2. Removes volumes
3. Removes images
4. Rebuilds without cache
5. Starts the development environment

Keeping Your Fork Updated

Before starting new work, sync your fork with upstream:

git fetch upstream
git checkout main
git merge upstream/main
git push origin main

Environment Variables

Key environment variables for development:

Variable	Description	Default
POSTGRES_PASSWORD	PostgreSQL password	Generated by init
REDIS_PASSWORD	Redis password	Generated by init
VAULT_TOKEN	Vault root token	From vault-init logs
OPENROUTER_API_KEY	OpenRouter API key	Required
ANTHROPIC_API_KEY	Anthropic API key	Optional
OPENAI_API_KEY	OpenAI API key	Optional
FRONTEND_URL	Frontend URL	http://localhost:3000
NEXT_PUBLIC_BACKEND_URL	Backend API URL	http://localhost:5080
NEXT_PUBLIC_WEBSOCKET_URL	WebSocket URL	ws://localhost:5006

Testing Vault

Test that Vault is working correctly:

# Store a test secret
vault kv put aurora/users/test-secret value='hello'

# Retrieve the test secret
vault kv get aurora/users/test-secret

Troubleshooting

Services Won’t Start

Ensure .env file exists and contains required variables:

make init

Database Connection Issues

Check PostgreSQL is running:

docker ps | grep postgres

View PostgreSQL logs:

make logs postgres

Port Conflicts

If ports are already in use, stop conflicting services or modify ports in docker-compose.yaml.

Network Issues

Reset the Docker network:

make down
docker network prune
make dev

Next Steps

Architecture Deep Dive

Learn about Aurora’s architecture and codebase structure

Contributing Guidelines

Read the contribution guidelines before submitting PRs

Testing Guide

Learn how to test your changes