Quick Start

Prerequisites

Requirement	Minimum version
Python	3.14.x
Poetry	1.8
Docker + Compose	any recent version (for MongoDB)

---

Docker Compose (recommended)

1. Check out the workspace

The quickstart docker-compose.yaml lives at the workspace root, one level above OpenTremor-core — it bind-builds OpenTremor-core, both Terraform analyzer repos, OpenTremor-dashboard, and OpenTremor-docs as siblings, all behind one HAProxy front door. Clone or check out all five repos side by side, then run everything from that root directory.

2. Start the full stack

A ready-to-use config (configs/opentremor-local.yaml, at the workspace root) is included — no manual MongoDB initialisation needed, mongodb’s indexes are created on first boot. It’s mounted read-only into the core container and shared with docker-compose.dev.yaml, so both local stacks read one file; see configs/README.md for why the per-repo configs still carry their own copy of the dev credentials.

docker compose up --build

The --build flag builds opentremor-core-test:latest (core + both analyzers, a local-test-only bundled image), opentremor-dashboard:latest, and opentremor-docs-test:latest on first run. Subsequent starts can omit it: docker compose up.

Everything is served through HAProxy at one URL:

Service	URL
Everything (API, dashboard, docs)	http://localhost:8080
OpenTremor Core API directly	http://localhost:8000
Dashboard directly	http://localhost:3001
Docs directly	http://localhost:4321

Hitting a service’s own port directly still renders pages, but client-side calls that assume HAProxy’s routing won’t resolve — use :8080 for the real thing.

Tip

server.dashboard_base_url isn’t set by the config file — set it once after the stack is up so invite links and the GitHub App manifest flow point at the right place:

curl -X PATCH http://localhost:8080/admin/settings \
  -H "X-API-Key: local-dev-key" -H "Content-Type: application/json" \
  -d '{"server_dashboard_base_url": "http://localhost:8080/dashboard"}'

Note

Prometheus, Grafana, and a Mongo admin UI are not part of this quickstart — they live in the separate OpenTremor-monitoring repo. See Metrics for the /metrics endpoint this server exposes on its own, with no extra installation.

Local development

1. Install dependencies

poetry install

2. Start MongoDB

docker compose up mongodb -d

3. Initialise the database

poetry run python src/tools/init_mongo.py

4. Start the server

poetry run uvicorn opentremor_core.controllers.app:app --reload

Or use the bundled entrypoint:

poetry run python src/server.py

Variable	Default	Description
CONFIG_FILE	configs/opentremor-core-local.yaml	Path to the YAML config
HOST	0.0.0.0	Bind address
PORT	8000	Bind port

In-memory (no database)

For quick experiments or running tests without MongoDB:

# whichever config your CONFIG_FILE points at — e.g. opentremor-core-local.yaml
storage:
  backend: "memory"

Caution

Data is lost when the server restarts. Use this for tests and local dev only.

---

Verify the server

curl http://localhost:8000/health
# {"status": "healthy", "timestamp": "..."}

curl http://localhost:8000/analyzers
# {"analyzers": [{"name": "terraform-plan", "description": "..."}, {"name": "terraform-code-change", ...}]}

Tip

With no auth.api_key configured (the default), every request is treated as the owner of a synthetic default organization — nothing to register, just start calling endpoints. The rest of this section assumes that default, no-auth setup. See Authentication for a real multi-tenant deployment.

---

Next steps

Two ways to run your first analysis

Let the server call the LLM itself — Server-Side Analysis, one call in, a report out — or drive the loop yourself — Client-Led Loop, full control over the LLM call. Then see Triage a Finding and Authentication for what comes after.