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

# 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](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:

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

```bash theme={null}
git remote add upstream https://github.com/Arvo-AI/aurora.git
```

### 3. Initialize Configuration

Run the initialization script to generate secure secrets:

```bash theme={null}
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](https://openrouter.ai/keys)
* **Anthropic**: Get a key at [https://console.anthropic.com/settings/keys](https://console.anthropic.com/settings/keys)
* **OpenAI**: Get a key at [https://platform.openai.com/api-keys](https://platform.openai.com/api-keys)

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

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

```bash theme={null}
docker logs vault-init 2>&1 | grep "Root Token:"
```

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

```bash theme={null}
nano .env
# Add:
VAULT_TOKEN=hvs.xxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

### 7. Restart Aurora

Restart the services to load the Vault token:

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

## Access the Application

Once all services are running, you can access:

* **Frontend**: [http://localhost:3000](http://localhost:3000)
* **REST API**: [http://localhost:5080](http://localhost:5080)
* **Chatbot WebSocket**: ws\://localhost:5006
* **Vault UI**: [http://localhost:8200](http://localhost:8200)
* **SeaweedFS File Browser**: [http://localhost:8888](http://localhost:8888)
* **SeaweedFS Cluster Status**: [http://localhost:9333](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:

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

View logs for a specific service:

```bash theme={null}
make logs frontend
make logs aurora-server
make logs celery_worker
```

For detailed backend logs:

```bash theme={null}
docker logs -f aurora-celery_worker-1
```

### Stopping the Environment

Stop all containers:

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

### Rebuilding Services

Rebuild only the backend API:

```bash theme={null}
make rebuild-server
```

Rebuild all containers:

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

### Clean Rebuild

For a complete fresh build without cache:

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

```bash theme={null}
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](http://localhost:3000) |
| `NEXT_PUBLIC_BACKEND_URL`   | Backend API URL     | [http://localhost:5080](http://localhost:5080) |
| `NEXT_PUBLIC_WEBSOCKET_URL` | WebSocket URL       | ws\://localhost:5006                           |

## Testing Vault

Test that Vault is working correctly:

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

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

### Database Connection Issues

Check PostgreSQL is running:

```bash theme={null}
docker ps | grep postgres
```

View PostgreSQL logs:

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

```bash theme={null}
make down
docker network prune
make dev
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Architecture Deep Dive" icon="building" href="/development/architecture-deep-dive">
    Learn about Aurora's architecture and codebase structure
  </Card>

  <Card title="Contributing Guidelines" icon="code-pull-request" href="/development/contributing">
    Read the contribution guidelines before submitting PRs
  </Card>

  <Card title="Testing Guide" icon="flask" href="/development/testing">
    Learn how to test your changes
  </Card>
</CardGroup>