Development Environment Setup

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:

Go to https://github.com/Arvo-AI/aurora
Click the “Fork” button in the top right
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:

Stops all containers
Removes volumes
Removes images
Rebuilds without cache
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

Get Started

Core Features

Architecture

Deployment

Configuration

Integrations

Cloud Providers

Observability

Development

Guides

Reference

Help

​Prerequisites

​Initial Setup

​1. Fork and Clone the Repository

​2. Add Upstream Remote

​3. Initialize Configuration

​4. Configure LLM API Key

​5. Start Development Environment

​6. Configure Vault Token

​7. Restart Aurora

​Access the Application

​Development Workflow

​Hot Reloading

​Viewing Logs

​Stopping the Environment

​Rebuilding Services

​Clean Rebuild

​Keeping Your Fork Updated

​Environment Variables

​Testing Vault

​Troubleshooting

​Services Won’t Start

​Database Connection Issues

​Port Conflicts

​Network Issues

​Next Steps