Development Setup

OpenTremor is split across several repositories — this page covers developing against this repository (the core server). For a full local stack (core + an analyzer + dashboard + MongoDB) in one command, see the docker-compose.yaml at the root of the opentremor workspace that checks out all the repos as siblings.

Prerequisites

Tool	Version	Purpose
Python	3.14.x	Runtime
Poetry	1.8+	Dependency management
Docker	any	MongoDB for integration tests

Install

git clone https://github.com/your-org/opentremor-core
cd opentremor-core
poetry install

This installs runtime and dev dependencies (pytest, black, isort, …) but no analyzer — GET /analyzers returns an empty list until you install one. To run the full test suite (including the tests that exercise a real analyzer end-to-end), also check out each analyzer repo you want (e.g. opentremor-analyzer-terraform-plan, opentremor-analyzer-terraform-code-change — each is independent, install as many or as few as you need) as sibling directories and run:

poetry install --with internal

Start services

docker compose up mongodb -d
poetry run python src/tools/init_mongo.py

A default superadmin account is available out of the box via auth.default_admin_email/default_admin_password — in configs/opentremor-core-local.yaml when running the server directly, or in the workspace root’s shared configs/opentremor-local.yaml when running either docker stack. See Configuration Reference — auth.

Run the server (dev mode)

poetry run uvicorn opentremor_core.controllers.app:app \
  --reload \
  --host 0.0.0.0 \
  --port 8000

Or with the bundled server entrypoint (reads HOST, PORT, CONFIG_FILE env vars):

CONFIG_FILE=configs/opentremor-core-local.yaml poetry run python src/server.py

Project layout

opentremor-core/
├── configs/
│   ├── opentremor-core.yaml          This repo's own standalone docker stack (MongoDB)
│   ├── opentremor-core-local.yaml    Local dev (in-memory, default)
│   ├── opentremor-core-prod.yaml     Operator's cloud SaaS deployment
│   └── opentremor-core-tests.yaml    Test suite config
├── src/
│   ├── opentremor_core/   Python package — server framework, no analyzers
│   ├── tests/                    Test suite
│   ├── tools/                    CLI utilities
│   └── server.py                 Uvicorn entrypoint
├── pyproject.toml
├── Dockerfile
└── docker-compose.yaml           This repo alone (app + MongoDB, no analyzer/dashboard)

Code style

# Format
poetry run black src/

# Sort imports
poetry run isort src/

# Both (typical pre-commit)
poetry run black src/ && poetry run isort src/

Documentation

Docs live in a separate opentremor-docs repository:

cd ../opentremor-docs
npm install
npm run dev      # live-reload dev server at http://localhost:4321
npm run build    # static site → dist/

Reaching the dev server on a hostname other than localhost

Astro’s dev server is Vite, and Vite refuses requests whose Host header it doesn’t recognise — a DNS-rebinding protection. Reached through a proxy or on a real domain it answers Blocked request. This host ("…") is not allowed. instead of the site. List the extra hostnames in DOCS_ALLOWED_HOSTS (comma-separated; * disables the check entirely):

DOCS_ALLOWED_HOSTS=docs.example.com npm run dev -- --host

This affects npm run dev only. npm run build output is static files with no dev server involved, so a production deployment never needs the variable — the workspace’s docker-compose.dev.yaml sets it for its docs service, docker-compose.prod.yaml does not.