Local development

Atlas runs locally with Docker Compose. The frontend and backend can also run on the host against the compose-managed data services for a faster edit loop.

Prerequisites

Docker + Docker Compose
Node.js ≥ 18 (frontend)
Python 3.11+ (backend, if running on host)
A populated .env (copy from .env.example)

Bring up the stack

cp .env.example .env          # then fill in secrets (see Configuration)
docker compose up -d          # full stack
docker compose ps             # verify services are healthy
docker compose logs -f osint-api

docker-compose.dev.yml provides a lighter/dev-oriented overlay; the base docker-compose.yml brings up the full set of services (API, UI, Postgres, Neo4j, Redis, MinIO, Keycloak, Temporal, Langfuse).

Run the frontend on the host

cd frontend
npm install
npm run dev        # Vite dev server, proxies /api and /realms

The Vite dev server proxies /api to the backend and /realms, /resources to Keycloak so auth stays same-origin. The HMR client port is configurable via VITE_HMR_CLIENT_PORT when running behind Docker port mapping. See Frontend architecture.

Migrations

Flyway runs automatically when the stack starts. To inspect or re-run:

docker compose logs flyway              # see migration output
docker compose run --rm flyway info     # current schema version & pending

Migrations live in migrations/ (130+ versioned scripts). The active ontology is published into ontology_schema_versions by a companion migration and checked for drift in CI.

Verifying the system is up

curl -s localhost:${API_PORT:-8000}/health        # liveness
curl -s localhost:${API_PORT:-8000}/health/ready   # readiness (deps initialised)

Open the supporting UIs:

UI	Default
Atlas Console	the configured `UI_PORT`
Temporal UI	the `temporal-ui` service
Keycloak admin	`KEYCLOAK_PORT`
Langfuse	`LANGFUSE_PORT`
MinIO console	the MinIO console port

Pre-flight

Before running tests or starting servers, check whether instances are already running so you don't start duplicates. Always run test suites in the background.

Tests

# Backend (pytest)
pytest -q                      # see pytest.ini

# Frontend (Vitest)
cd frontend && npm run test

See Reference → Environment variables for the full .env surface and Configuration for what each group controls.

Prerequisites​

Bring up the stack​

Run the frontend on the host​

Migrations​

Verifying the system is up​

Tests​