Installation Guide

This guide covers all installation methods for AuroraSOC, from a compose-runtime quick start to a full production deployment with GPU-accelerated LLM inference.

If you want the operator-focused, step-by-step guide for getting the agent mesh running locally, use AI Agent Fleet Deployment.

Compose runtime selection

AuroraSOC now auto-detects Docker or Podman in the repository tooling and compose-backed fleet runtime.

COMPOSE_BIN overrides the compose binary used by the Makefile and operator scripts.
CONTAINER_BIN overrides direct cp, exec, and run container commands in smoke validation, and defaults to COMPOSE_BIN.
FLEET_COMPOSE_BIN overrides the compose binary used by the backend fleet reconciler and API runtime.

The examples below still show Podman commands for Linux-first operators. When you use Docker, replace podman with docker, or set COMPOSE_BIN=docker when using the repository Make targets and scripts.

Method 1: Compose Runtime (Quick Start)

The simplest way to run AuroraSOC with the default application stack:

# Clone the repository
git clone https://github.com/ahmeddwalid/AuroraSOC
cd AuroraSOC

# Copy and configure the environment file
cp .env.example .env
# Edit .env and set PG_PASSWORD, JWT_SECRET_KEY, API_SERVICE_KEY at minimum

# Start the default stack with the auto-detected compose runtime
make docker-up

# Check service health
make docker-logs

To pin the runtime explicitly, use either COMPOSE_BIN=podman make docker-up or COMPOSE_BIN=docker make docker-up.

This starts the default Python API and event-processing path plus the core data and UI services. It does not enable the profile-gated agent fleet or the optional rust-core fast path.

If you want the specialist agents, add --profile agents. If you also want the Rust ingest and attestation fast path, add --profile rust-core.

Production Compose Setup

For production, configure environment variables:

# Generate secure secrets
export JWT=$(openssl rand -hex 32)
export API_KEY=$(openssl rand -hex 32)

# Create production .env file
cat > .env << EOF
# Database
PG_PASSWORD=your-secure-password-here

# Security
JWT_SECRET_KEY=${JWT}
API_SERVICE_KEY=${API_KEY}

# Grafana
GRAFANA_PASSWORD=your-grafana-password

# Vault
VAULT_TOKEN=your-vault-token

# LLM
VLLM_HF_MODEL=ibm-granite/granite-4.1-8b
HF_TOKEN=your_huggingface_token

# Environment
ENVIRONMENT=production
SYSTEM_MODE=real
LOG_LEVEL=WARNING
DEBUG=false
EOF

# Deploy the default stack
podman compose --env-file .env up -d

Reuse the same profiles during deployment that you use during development. For example, --profile agents enables the agent fleet and --profile rust-core adds the optional Rust fast path.

Method 2: Full GPU Stack with vLLM (AI-Powered SOC)

This is the recommended method for running actual AI agent investigations with IBM Granite 4 inference on a consumer GPU (RTX 4060 8 GB or better).

Prerequisites

Podman 5.0+ (podman --version)
NVIDIA GPU with 8+ GB VRAM
NVIDIA driver installed (nvidia-smi should work)

Step 1: Install NVIDIA Container Toolkit (Fedora/RHEL)

# Add the NVIDIA container toolkit repository
sudo dnf config-manager \
  --add-repo https://nvidia.github.io/libnvidia-container/stable/rpm/nvidia-container-toolkit.repo

# Install the toolkit
sudo dnf install -y nvidia-container-toolkit

# Generate the CDI specification so Podman can access the GPU
sudo nvidia-ctk cdi generate --output=/etc/cdi/nvidia.yaml

# Verify the CDI device is available
nvidia-ctk cdi list
# Expected output: nvidia.com/gpu=0  (or similar)

Ubuntu/Debian

For Ubuntu, replace dnf commands with:

curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
  sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
  sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit
sudo nvidia-ctk cdi generate --output=/etc/cdi/nvidia.yaml

Step 2: Create the Environment File

cp .env.example .env

Edit .env and set the following values:

# Required: database password
PG_PASSWORD=your-secure-db-password

# Required: security secrets (generate with: openssl rand -hex 32)
JWT_SECRET_KEY=<openssl rand -hex 32 output>
API_SERVICE_KEY=<openssl rand -hex 32 output>

# Required: HuggingFace token (https://huggingface.co/settings/tokens)
# Needed to download IBM Granite 4 on first run
HF_TOKEN=hf_your_token_here

# LLM model to serve via vLLM
VLLM_HF_MODEL=ibm-granite/granite-4.1-8b

# Runtime mode: dummy | dry_run | real
# dry_run = live reads and analysis previews, no mutations (safe for testing)
SYSTEM_MODE=dry_run

Makefile helper

make env-init generates JWT_SECRET_KEY and API_SERVICE_KEY automatically and writes them into .env.

Step 3: Start the Full Stack

# Infrastructure + vLLM GPU inference + the full specialist fleet
podman compose \
  -f docker-compose.yml \
  -f docker-compose.gpu.yml \
  --profile agents \
  up -d

Add --profile rust-core only if you want the optional Rust ingest and attestation service alongside the agent fleet.

Services started:

Service	Port	Description
`postgres` (+ pgvector)	5432	Primary database with vector search
`redis`	6379	Cache and event streams
`nats`	4222	Cross-site federation
`mosquitto`	8883	MQTT for IoT/CPS devices
`vllm`	8001	IBM Granite 4 served via OpenAI-compatible API
`api`	8000	FastAPI REST + WebSocket gateway
`dashboard`	3000	Next.js SOC dashboard
`orchestrator`	9000	Master AI orchestrator
13 specialist agents	9001–9016	Domain-specific AI agents
`rust-core` (optional profile)	`RUST_CORE_HOST_PORT` (container `8080`)	High-performance event processor
`prometheus`	9090	Metrics collection
`grafana`	3001	Metrics visualization

First Run — Model Download

The first startup downloads IBM Granite 4 (~15 GB) from HuggingFace into a persistent volume. Monitor progress with:

podman compose logs -f vllm

Wait for Application startup complete before sending requests to the API. This may take 10–30 minutes depending on your connection.

Step 4: Run Database Migrations

# Activate the Python virtualenv
source .venv/bin/activate

# Apply all schema migrations
alembic upgrade head

Or run inside the API container if you don't have a local virtualenv:

podman compose exec api alembic upgrade head

Step 5: Verify the Stack

# API health
curl http://localhost:8000/api/v1/health

# vLLM models endpoint (confirms model loaded)
curl http://localhost:8001/v1/models

# Check all containers
podman compose -f docker-compose.yml -f docker-compose.gpu.yml ps

# Dashboard
open http://localhost:3000   # or xdg-open http://localhost:3000 on Linux

Agent Profile Tiers

If you do not need the full agent fleet, choose a smaller profile to save resources:

Profile	Agents included	RAM needed
`agents-core`	Orchestrator plus the baseline triage workflow	~8 GB
`agents-extended`	Adds broader investigation specialists	~16 GB
`agents-specialized`	Adds deep investigation and reporting specialists	~24 GB
`agents`	Full specialist fleet	~32 GB

# Minimal triage fleet (4 agents)
podman compose -f docker-compose.yml -f docker-compose.gpu.yml --profile agents-core up -d

# Core + domain specialists (8 agents)
podman compose -f docker-compose.yml -f docker-compose.gpu.yml \
  --profile agents-core --profile agents-extended up -d

# Add the optional Rust fast path to any profile combination
podman compose -f docker-compose.yml -f docker-compose.gpu.yml \
  --profile agents --profile rust-core up -d

The rust-core profile is independent of the agent tiers. Enable it only when you want the Rust normalization and attestation path.

Makefile Shortcuts

make docker-up        # Start default compose stack
make docker-down      # Stop compose stack
make docker-logs      # Follow all container logs
make vllm-up          # Start vLLM service only
make vllm-logs        # Follow vLLM logs
make docker-build     # Rebuild all images

Method 3: Local Development Setup

For active development with hot-reload:

Step 1: Infrastructure Services

# Start only infrastructure (no app services)
podman compose -f docker-compose.dev.yml up -d

Step 2: Python Backend

# Create virtual environment
python3.12 -m venv .venv
source .venv/bin/activate

# Install with dev extras
pip install -e ".[dev]"

# Run migrations
alembic upgrade head

# Start API with hot-reload
uvicorn aurorasoc.api.main:app --host 0.0.0.0 --port 8000 --reload

Step 3: Dashboard

cd dashboard
npm install
npm run dev

Step 4: LLM Backend (Optional)

For CPU-only or quick local testing, Ollama is an alternative to vLLM:

# Install Ollama (https://ollama.com)
curl -fsSL https://ollama.com/install.sh | sh

# Pull recommended models
ollama pull granite4:8b         # Default agent model
ollama pull granite4:dense      # Orchestrator model

For GPU-accelerated inference with the full agent fleet, use Method 2 above.

Method 4: Building from Source

Build the Rust Core Engine (Optional)

cd rust_core
cargo build --release
# Binary at: target/release/aurora-core

Enable the Rust service in Compose only when you need that fast path:

podman compose --profile rust-core up -d

Build Container Images

# Build all images
make docker-build

# Or build individually with Podman
podman build -f Dockerfile.python -t aurorasoc/api:latest .
podman build -f Dockerfile -t aurorasoc/rust-core:latest ./rust_core
podman build -f Dockerfile.dashboard -t aurorasoc/dashboard:latest .

Build Firmware (Advanced)

See the Firmware Guide for building embedded firmware for STM32, nRF52840, and ESP32-S3 devices.

Platform-Specific Setup Guides

These guides walk through installing every prerequisite and then running the full GPU stack (Method 2) on Windows, Debian, and Arch Linux. If you are on Fedora/RHEL, follow Method 2 directly — its steps are already written for that platform.

Windows (WSL2)

AuroraSOC runs on Windows through WSL2 (Windows Subsystem for Linux). All container commands execute inside a WSL2 Ubuntu environment. GPU passthrough to WSL2 requires an NVIDIA GPU and the NVIDIA CUDA on WSL2 driver package installed on the Windows side.

Step 1: Enable WSL2 and install Ubuntu

Open PowerShell as Administrator:

# Enable WSL and the Virtual Machine Platform features
wsl --install

# After reboot, install Ubuntu 24.04 LTS
wsl --install -d Ubuntu-24.04

# Set WSL2 as the default version (if not already)
wsl --set-default-version 2

After reboot, launch Ubuntu 24.04 from the Start menu and complete the initial user setup (username + password). All subsequent commands run inside this Ubuntu terminal.

Step 2: Install NVIDIA WSL2 GPU driver (Windows side)

Download and install the NVIDIA CUDA on WSL2 driver from: https://developer.nvidia.com/cuda/wsl

This is a single Windows installer (.exe) — not the standard Linux CUDA toolkit. It installs the driver bridge that exposes the GPU inside WSL2.

Verify inside WSL2 after install:

nvidia-smi
# Should print GPU name, driver version, and CUDA version

If nvidia-smi is not found, reboot Windows and try again.

Step 3: Install system packages inside WSL2

sudo apt-get update && sudo apt-get upgrade -y
sudo apt-get install -y \
  curl wget git gnupg ca-certificates \
  build-essential python3.12 python3.12-venv python3-pip \
  nodejs npm

If python3.12 is not in the Ubuntu 24.04 default repos, add the deadsnakes PPA:

sudo add-apt-repository ppa:deadsnakes/ppa -y
sudo apt-get update
sudo apt-get install -y python3.12 python3.12-venv python3.12-dev

Step 4: Install Podman and podman-compose

# Install Podman
sudo apt-get install -y podman

# Install podman-compose
pip3 install podman-compose
# Or via apt if available:
sudo apt-get install -y podman-compose

# Verify
podman --version
podman-compose --version

Podman Desktop (optional)

Podman Desktop is a GUI application for Windows that manages the WSL2 Podman machine visually. It is optional — all AuroraSOC operations use the command line.

Step 5: Install NVIDIA Container Toolkit inside WSL2

# Add NVIDIA container toolkit repository
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey \
  | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg

curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list \
  | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' \
  | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit

# Generate the CDI spec so Podman can see the GPU
sudo nvidia-ctk cdi generate --output=/etc/cdi/nvidia.yaml

# Verify CDI device is listed
nvidia-ctk cdi list
# Expected: nvidia.com/gpu=0

Step 6: Clone AuroraSOC and configure environment

# Clone inside WSL2 filesystem (not /mnt/c/) for best I/O performance
cd ~
git clone https://github.com/ahmeddwalid/AuroraSOC
cd AuroraSOC

# Create virtual environment
python3.12 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# Create .env
cp .env.example .env

Edit .env — use nano .env or any editor:

PG_PASSWORD=your-secure-db-password
JWT_SECRET_KEY=<run: openssl rand -hex 32>
API_SERVICE_KEY=<run: openssl rand -hex 32>
HF_TOKEN=hf_your_huggingface_token
VLLM_HF_MODEL=ibm-granite/granite-4.1-8b
SYSTEM_MODE=dry_run

Step 7: Start the full stack

podman compose \
  -f docker-compose.yml \
  -f docker-compose.gpu.yml \
  --profile agents \
  up -d

Monitor the first-run model download (this downloads ~15 GB):

podman compose logs -f vllm

Step 8: Run database migrations

source .venv/bin/activate
alembic upgrade head

Step 9: Verify

curl http://localhost:8000/api/v1/health
curl http://localhost:8080/v1/models

Open the dashboard in your Windows browser at http://localhost:3000. WSL2 port forwarding is automatic — ports bound inside WSL2 are accessible from Windows.

WSL2 resource limits

By default WSL2 may be limited to 50% of system RAM. If you have 32 GB RAM and need more headroom, create %USERPROFILE%\.wslconfig on Windows:

[wsl2]
memory=28GB
processors=12
swap=8GB

Then restart WSL2: wsl --shutdown in PowerShell, then relaunch Ubuntu.

Debian (Bookworm / Bullseye)

Tested on Debian 12 (Bookworm). Most steps also apply to Debian 11 (Bullseye) with the same package names.

Step 1: Update system and install base packages

sudo apt-get update && sudo apt-get upgrade -y
sudo apt-get install -y \
  curl wget git gnupg ca-certificates lsb-release \
  build-essential python3.12 python3.12-venv python3-pip \
  nodejs npm

If python3.12 is not available (Debian 11), add the deadsnakes PPA or build from source:

# Debian 12 has python3.11 by default; get 3.12 from backports or deadsnakes
sudo add-apt-repository ppa:deadsnakes/ppa -y   # requires software-properties-common
sudo apt-get update
sudo apt-get install -y python3.12 python3.12-venv python3.12-dev

Step 2: Install Podman

Debian 12 ships Podman 4.x in the default repos. For Podman 5.x (required), use the Kubic repository:

# Add the Kubic repository for the latest Podman
. /etc/os-release
echo "deb https://download.opensuse.org/repositories/devel:/kubic:/libcontainers:/unstable/Debian_${VERSION_ID}/ /" \
  | sudo tee /etc/apt/sources.list.d/devel:kubic:libcontainers:unstable.list

curl -fsSL "https://download.opensuse.org/repositories/devel:/kubic:/libcontainers:/unstable/Debian_${VERSION_ID}/Release.key" \
  | sudo gpg --dearmor -o /etc/apt/keyrings/libcontainers.gpg

sudo apt-get update
sudo apt-get install -y podman

# Verify version is 5.x+
podman --version

Step 3: Install podman-compose

pip3 install --user podman-compose

# Add local bin to PATH if needed
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

podman-compose --version

Step 4: Install NVIDIA Container Toolkit (GPU systems only)

Skip this step if you don't have an NVIDIA GPU (use Ollama instead — see Method 3).

# Add NVIDIA container toolkit repository
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey \
  | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg

curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list \
  | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' \
  | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit

# Generate the CDI specification
sudo nvidia-ctk cdi generate --output=/etc/cdi/nvidia.yaml

# Verify
nvidia-ctk cdi list

Step 5: Clone and configure

git clone https://github.com/ahmeddwalid/AuroraSOC
cd AuroraSOC

# Create virtual environment
python3.12 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# Environment file
cp .env.example .env

Edit .env (nano .env):

PG_PASSWORD=your-secure-db-password
JWT_SECRET_KEY=<run: openssl rand -hex 32>
API_SERVICE_KEY=<run: openssl rand -hex 32>
HF_TOKEN=hf_your_huggingface_token
VLLM_HF_MODEL=ibm-granite/granite-4.1-8b
SYSTEM_MODE=dry_run

Step 6: Start the stack

With GPU (vLLM):

podman compose \
  -f docker-compose.yml \
  -f docker-compose.gpu.yml \
  --profile agents \
  up -d

Without GPU (CPU / Ollama):

# Start infrastructure and services only
podman compose -f docker-compose.dev.yml up -d

# In a separate terminal, run Ollama
curl -fsSL https://ollama.com/install.sh | sh
ollama pull granite4:8b

# Set LLM_BACKEND=ollama in .env, then start the API locally
source .venv/bin/activate
uvicorn aurorasoc.api.main:app --host 0.0.0.0 --port 8000

Step 7: Database migrations and verify

source .venv/bin/activate
alembic upgrade head

curl http://localhost:8000/api/v1/health
# GPU stack only:
curl http://localhost:8080/v1/models

Arch Linux

Tested on Arch Linux with the standard pacman package manager. AUR helpers (yay or paru) are used for packages not in the official repos.

Step 1: Install system dependencies

sudo pacman -Syu
sudo pacman -S --needed \
  base-devel git curl wget \
  python python-pip \
  nodejs npm

AuroraSOC requires Python 3.12+. Arch ships the latest Python, so no extra steps are needed.

Step 2: Install Podman and podman-compose

Both are available in the official repos:

sudo pacman -S --needed podman podman-compose

# Verify
podman --version       # Should be 5.x+
podman-compose --version

Enable the podman socket if needed for rootless operation:

systemctl --user enable --now podman.socket

Step 3: Configure rootless Podman (recommended)

Arch requires newuidmap and newgidmap for rootless containers:

sudo pacman -S --needed shadow

# Verify subuid/subgid ranges are set for your user
grep $(whoami) /etc/subuid /etc/subgid
# Should show lines like: ahmed:100000:65536
# If missing, add them:
sudo usermod --add-subuids 100000-165535 --add-subgids 100000-165535 $(whoami)

Step 4: Install NVIDIA Container Toolkit (GPU systems only)

The nvidia-container-toolkit package is available in the AUR:

# Using yay
yay -S nvidia-container-toolkit

# Or using paru
paru -S nvidia-container-toolkit

# Generate the CDI specification
sudo nvidia-ctk cdi generate --output=/etc/cdi/nvidia.yaml

# Verify
nvidia-ctk cdi list
# Expected: nvidia.com/gpu=0

NVIDIA driver on Arch

Install the NVIDIA proprietary driver before the container toolkit:

sudo pacman -S --needed nvidia nvidia-utils
# Reboot after install

For open-kernel-module variant: sudo pacman -S --needed nvidia-open nvidia-utils

Step 5: Clone and configure

git clone https://github.com/ahmeddwalid/AuroraSOC
cd AuroraSOC

# Create virtual environment
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# Environment file
cp .env.example .env

Edit .env:

PG_PASSWORD=your-secure-db-password
JWT_SECRET_KEY=<run: openssl rand -hex 32>
API_SERVICE_KEY=<run: openssl rand -hex 32>
HF_TOKEN=hf_your_huggingface_token
VLLM_HF_MODEL=ibm-granite/granite-4.1-8b
SYSTEM_MODE=dry_run

Step 6: Start the stack

With GPU (vLLM):

podman compose \
  -f docker-compose.yml \
  -f docker-compose.gpu.yml \
  --profile agents \
  up -d

Without GPU:

# Install Ollama
yay -S ollama
# Or via the official installer:
curl -fsSL https://ollama.com/install.sh | sh

systemctl --user start ollama
ollama pull granite4:8b

# Set LLM_BACKEND=ollama in .env, then start infrastructure
podman compose -f docker-compose.dev.yml up -d
source .venv/bin/activate
uvicorn aurorasoc.api.main:app --host 0.0.0.0 --port 8000

Step 7: Database migrations and verify

source .venv/bin/activate
alembic upgrade head

curl http://localhost:8000/api/v1/health
# GPU stack only:
curl http://localhost:8080/v1/models

# Dashboard
xdg-open http://localhost:3000

Arch firewall (nftables)

If you use nftables or ufw, ensure ports 8000, 3000, 5432 (local), and 8080 are accessible from localhost. Podman rootless uses the pasta network backend on Arch by default, which handles port forwarding without root.

Verifying the Installation

After installation, verify each component:

# API health check
curl http://localhost:8000/api/v1/health

# vLLM model list (GPU stack only)
curl http://localhost:8080/v1/models

# Dashboard (Linux)
xdg-open http://localhost:3000

# PostgreSQL
podman compose exec postgres pg_isready -U aurorasoc

# Redis
podman compose exec redis redis-cli ping

# NATS
curl http://localhost:8222/healthz

Troubleshooting

If the API starts but database operations fail, AuroraSOC automatically falls back to in-memory demo data. Check podman compose logs postgres for database connectivity issues.

Updating AuroraSOC

# Pull latest changes
git pull origin main

# Update Python dependencies
pip install -e ".[dev]"

# Run any new migrations
alembic upgrade head

# Rebuild images and restart services
podman compose build
podman compose up -d

# If you run profiles, re-apply them explicitly
# podman compose --profile agents --profile rust-core up -d

Method 1: Compose Runtime (Quick Start)​

Production Compose Setup​

Method 2: Full GPU Stack with vLLM (AI-Powered SOC)​

Prerequisites​

Step 1: Install NVIDIA Container Toolkit (Fedora/RHEL)​

Step 2: Create the Environment File​

Step 3: Start the Full Stack​

Step 4: Run Database Migrations​

Step 5: Verify the Stack​

Agent Profile Tiers​

Makefile Shortcuts​

Method 3: Local Development Setup​

Step 1: Infrastructure Services​

Step 2: Python Backend​

Step 3: Dashboard​

Step 4: LLM Backend (Optional)​

Method 4: Building from Source​

Build the Rust Core Engine (Optional)​

Build Container Images​

Build Firmware (Advanced)​

Platform-Specific Setup Guides​

Windows (WSL2)​

Step 1: Enable WSL2 and install Ubuntu​

Step 2: Install NVIDIA WSL2 GPU driver (Windows side)​

Step 3: Install system packages inside WSL2​

Step 4: Install Podman and podman-compose​

Step 5: Install NVIDIA Container Toolkit inside WSL2​

Step 6: Clone AuroraSOC and configure environment​

Step 7: Start the full stack​

Step 8: Run database migrations​

Step 9: Verify​

Debian (Bookworm / Bullseye)​

Step 1: Update system and install base packages​

Step 2: Install Podman​

Step 3: Install podman-compose​

Step 4: Install NVIDIA Container Toolkit (GPU systems only)​

Step 5: Clone and configure​

Step 6: Start the stack​

Step 7: Database migrations and verify​

Arch Linux​

Step 1: Install system dependencies​

Step 2: Install Podman and podman-compose​

Step 3: Configure rootless Podman (recommended)​

Step 4: Install NVIDIA Container Toolkit (GPU systems only)​

Step 5: Clone and configure​

Step 6: Start the stack​

Step 7: Database migrations and verify​

Verifying the Installation​

Updating AuroraSOC​

Method 1: Compose Runtime (Quick Start)

Production Compose Setup

Method 2: Full GPU Stack with vLLM (AI-Powered SOC)

Prerequisites

Step 1: Install NVIDIA Container Toolkit (Fedora/RHEL)

Step 2: Create the Environment File

Step 3: Start the Full Stack

Step 4: Run Database Migrations

Step 5: Verify the Stack

Agent Profile Tiers

Makefile Shortcuts

Method 3: Local Development Setup

Step 1: Infrastructure Services

Step 2: Python Backend

Step 3: Dashboard

Step 4: LLM Backend (Optional)

Method 4: Building from Source

Build the Rust Core Engine (Optional)

Build Container Images

Build Firmware (Advanced)

Platform-Specific Setup Guides

Windows (WSL2)

Step 1: Enable WSL2 and install Ubuntu

Step 2: Install NVIDIA WSL2 GPU driver (Windows side)

Step 3: Install system packages inside WSL2

Step 4: Install Podman and podman-compose

Step 5: Install NVIDIA Container Toolkit inside WSL2

Step 6: Clone AuroraSOC and configure environment

Step 7: Start the full stack

Step 8: Run database migrations

Step 9: Verify

Debian (Bookworm / Bullseye)

Step 1: Update system and install base packages

Step 2: Install Podman

Step 3: Install podman-compose

Step 4: Install NVIDIA Container Toolkit (GPU systems only)

Step 5: Clone and configure

Step 6: Start the stack

Step 7: Database migrations and verify

Arch Linux

Step 1: Install system dependencies

Step 2: Install Podman and podman-compose

Step 3: Configure rootless Podman (recommended)

Step 4: Install NVIDIA Container Toolkit (GPU systems only)

Step 5: Clone and configure

Step 6: Start the stack

Step 7: Database migrations and verify

Verifying the Installation

Updating AuroraSOC