ContextQMD
Back to Hyperswitch

Local Setup

api-reference/decision-engine-api-reference/local-setup.md

2026.07.29.16.7 KB
Original Source

Local Setup Guide

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:

  1. Published-image track — pull existing images.
  2. 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

ProfileDBIncludes
postgres-ghcrPostgreSQLAPI + PostgreSQL + Redis + Kafka + ClickHouse + PG migrations
postgres-localPostgreSQLAPI + PostgreSQL + Redis + Kafka + ClickHouse + PG migrations
mysql-ghcrMySQLAPI + MySQL + Redis + Kafka + ClickHouse + MySQL migrations + routing-config
mysql-localMySQLAPI + MySQL + Redis + Kafka + ClickHouse + MySQL migrations + routing-config

Dashboard profiles

ProfileDBIncludes
dashboard-postgres-ghcrPostgreSQLcore PG stack + dashboard + Mintlify docs
dashboard-postgres-localPostgreSQLcore PG stack + dashboard + Mintlify docs
dashboard-mysql-ghcrMySQLcore MySQL stack + dashboard + Mintlify docs
dashboard-mysql-localMySQLcore MySQL stack + dashboard + Mintlify docs

Optional profiles

ProfileAdds
monitoringPrometheus + Grafana
groovy-ghcrGroovy runner image
groovy-localGroovy runner built from local source
analytics-clickhouseKafka topic init + ClickHouse analytics bootstrap only

Fastest Bring-Up

One-Command Local Dev

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

bash
./oneclick.sh

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

bash
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:

bash
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:

bash
ONECLICK_KEEP_INFRA=1 ./oneclick.sh

API Only

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

API + Dashboard + Docs

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

With Monitoring

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

Make Targets

Common wrappers:

bash
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:

bash
make reset-analytics-clickhouse

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

Source Build And Run

PostgreSQL

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

MySQL

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

Docker Builds Without Compose

bash
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:

bash
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/

bash
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

bash
curl http://localhost:8080/health

Expected response:

json
{"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

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

Inspect migration jobs

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

Inspect analytics infrastructure

bash
docker compose logs kafka-init
docker compose logs clickhouse

Check the ClickHouse schema directly:

bash
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