Skip to main content

Local development setup

What this page is​

How to bring up AuroraSOC on a single developer host: the compose stack, the Granite model via Ollama, the FastAPI backend, and the operator console at localhost:3000.

Why it exists this way​

The build prompt's quality bar reads: a new backend engineer can read the developer docs and contribute a meaningful change within two weeks. That target is unreachable without a working local stack on day one. This page is the bring-up contract.

How it works​

Prerequisites (verified with the existing CI image):

  • Docker 24+ with Compose v2.
  • Python 3.13 with uv installed.
  • Node 20 LTS with pnpm.
  • Rust toolchain via rustup (the workspace pins 1.86.0 plus the nightly date in crates/edr-linux-ebpf/rust-toolchain.toml).
  • Linux kernel 5.10+ if you want the EDR sensor to attach (other components run fine on any kernel; the eBPF runtime alone has a kernel floor).

Bring-up sequence:

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

cp .env.example .env
# Edit .env: set the database passwords, the JWT secret, and the
# Redis password. The defaults are deliberately rejected by the
# settings validator so you cannot accidentally ship them.

docker compose -f infra/compose/docker-compose.yml up -d \
    postgres redis nats ollama

# Pull the Granite 4 model into Ollama.
docker compose exec ollama ollama pull granite4-soc-default

cd packages/backend
uv sync
uv run alembic upgrade head
uv run python -m aurorasoc.main

The operator console:

cd apps/operator-console
pnpm install
pnpm dev

Open http://localhost:3000. The default local auth provider creates an admin operator on first run; the password is logged once to the backend stdout.

Verifying the agent path end to end:

# Open a second backend shell.
uv run pytest tests/backend/test_agent_fleet_smoke.py -v

The smoke test brings up the workflow runner, queues one investigation, and asserts the agent returns a non-empty result. If it passes the local stack is healthy.

What goes wrong​

  • docker compose up fails on the postgres healthcheck. Most often the Postgres data volume from a previous run has a different password. Delete the volume (you will lose local data) or set POSTGRES_PASSWORD in .env to match.
  • Ollama pull fails with disk-space errors. The Granite 4 variants are 4–7 GB each; budget 30 GB free for the full fleet plus the small-tier defaults.
  • The eBPF sub-build during cargo check -p edr-linux fails with a missing rust-src. Run rustup component add rust-src --toolchain nightly-2026-04-18; see crates/edr-linux/build.rs for the toolchain it pins.
  • The operator console fails to log in with "no auth providers configured". The backend is not running or did not finish initialising. The login page only lists providers after the /api/v1/auth/providers endpoint succeeds.