Local Setup Guide

July 28, 2026 · View on GitHub

This is the canonical local startup guide for Decision Engine.

Prerequisites

Docker 20+
Docker Compose v2+
Git 2+

Required for source runs:

Rust 1.85+
PostgreSQL or MySQL
Redis
just — required for PostgreSQL source runs (just migrate-pg); MySQL can use diesel migration run directly

Runtime Tracks

Decision Engine supports two local tracks:

Published-image track — pull existing images.
Local-build track — build images or binaries from the current source tree.

Default tags used in this repo:

DECISION_ENGINE_TAG=v1.4
GROOVY_RUNNER_TAG=v1.4

Docker Compose Profiles

You must pass at least one profile.

Core runtime profiles

Profile	DB	Includes
`postgres-ghcr`	PostgreSQL	API + PostgreSQL + Redis + Kafka + ClickHouse + PG migrations
`postgres-local`	PostgreSQL	API + PostgreSQL + Redis + Kafka + ClickHouse + PG migrations
`mysql-ghcr`	MySQL	API + MySQL + Redis + Kafka + ClickHouse + MySQL migrations + routing-config
`mysql-local`	MySQL	API + MySQL + Redis + Kafka + ClickHouse + MySQL migrations + routing-config

Dashboard profiles

Profile	DB	Includes
`dashboard-postgres-ghcr`	PostgreSQL	core PG stack + dashboard + Mintlify docs
`dashboard-postgres-local`	PostgreSQL	core PG stack + dashboard + Mintlify docs
`dashboard-mysql-ghcr`	MySQL	core MySQL stack + dashboard + Mintlify docs
`dashboard-mysql-local`	MySQL	core MySQL stack + dashboard + Mintlify docs

Optional profiles

Profile	Adds
`monitoring`	Prometheus + Grafana
`groovy-ghcr`	Groovy runner image
`groovy-local`	Groovy runner built from local source
`analytics-clickhouse`	Kafka topic init + ClickHouse analytics bootstrap only

Fastest Bring-Up

One-Command Local Dev

For local source-run development with the full PostgreSQL analytics stack:

./oneclick.sh

For the full end-to-end regression gate owned by the Cypress branch:

npm run test:e2e

That command runs:

source-run validation through oneclick.sh
Docker Compose validation through dashboard-postgres-local
the full Cypress API/UI/docs smoke contract against both modes

Mode-specific entrypoints:

npm run test:e2e:source
npm run test:e2e:docker

This flow:

starts PostgreSQL, Redis, Kafka, ClickHouse, and the analytics init jobs with Docker Compose
waits for infra health
runs PostgreSQL migrations
starts the API locally with cargo run --no-default-features --features postgres
starts the dashboard locally with Vite on http://localhost:5173/

By default, Ctrl+C stops the local API/dashboard processes and any infra services that oneclick.sh started itself. To keep infra running after exit:

ONECLICK_KEEP_INFRA=1 ./oneclick.sh

API Only

docker compose --profile postgres-ghcr up -d

API + Dashboard + Docs

docker compose --profile dashboard-postgres-ghcr up -d

With Monitoring

docker compose --profile postgres-ghcr --profile monitoring up -d

Make Targets

Common wrappers:

make init-pg-ghcr
make init-pg-local
make init-mysql-ghcr
make init-mysql-local
make run-pg-ghcr
make run-mysql-local
make reset-analytics-clickhouse
make stop

Analytics Bootstrap

The Kafka to ClickHouse analytics path is bootstrapped automatically.

Kafka topics are created by kafka-init
ClickHouse loads analytics SQL from clickhouse/scripts/ on first boot
analytics data is stored in the named Docker volume clickhouse-data
normal restarts keep analytics history intact

If you need a clean analytics rebuild, use:

make reset-analytics-clickhouse

That removes the ClickHouse analytics volume and recreates the Kafka + ClickHouse analytics stack.

Source Build And Run

PostgreSQL

cargo build --release --no-default-features --features middleware,kms-aws,postgres
just migrate-pg
RUSTFLAGS="-Awarnings" cargo run --no-default-features --features postgres

MySQL

cargo build --release --features release
RUSTFLAGS="-Awarnings" cargo run --features release

Docker Builds Without Compose

docker build --platform=linux/amd64 -t decision-engine-mysql:local -f Dockerfile .
docker build --platform=linux/amd64 -t decision-engine-pg:local -f Dockerfile.postgres .

Example container run:

docker run --platform=linux/amd64 \
  -v $(pwd)/config/docker-configuration.toml:/local/config/development.toml \
  -p 8080:8080 \
  decision-engine-pg:local

Helm

Chart location: helm-charts/

cd helm-charts
helm dependency update
helm install my-release .

Use helm dependency update, not helm dependency build — the committed Chart.lock digest can drift out of sync with Chart.yaml, and build fails hard on any mismatch (Error: the lock file (Chart.lock) is out of sync with the dependencies file). update re-resolves and re-fetches the postgresql, mysql, and redis subcharts from the Bitnami repo unconditionally.

For image overrides, use image.repository, image.version, and image.pullPolicy. Verify with helm install --dry-run or helm template before applying to a cluster.

Verification

curl http://localhost:8080/health

Expected response:

{"message":"Health is good"}

Dashboard profiles also expose:

Dashboard: http://localhost:8081/dashboard/
Docs: http://localhost:8081/introduction
API examples: http://localhost:8081/api-refs/api-ref

Monitoring profile also exposes:

Prometheus: http://localhost:9090
Grafana: http://localhost:3000

Troubleshooting

Recreate a profile with clean volumes

docker compose --profile postgres-ghcr down -v
docker compose --profile postgres-ghcr up -d

Inspect migration jobs

docker compose logs db-migrator-postgres
docker compose logs db-migrator

Inspect analytics infrastructure

docker compose logs kafka-init
docker compose logs clickhouse

Check the ClickHouse schema directly:

curl --user decision_engine:decision_engine \
  "http://localhost:8123/?query=SHOW%20TABLES%20FROM%20default"

Common Next Files To Inspect

docker-compose.yaml
config/docker-configuration.toml
src/config.rs
src/app.rs