Getting Started

Running Merlon with the least effort, from nothing to a working operator dashboard.

If you want to look at a populated system rather than an empty one, start with the Demo Tour instead: it ships about 1,015 synthetic customers and 98 alerts, and needs no account.

Prerequisites

• Docker 24+
• Docker Compose v2+
• git

You do not need Go or Node.js installed locally — everything below runs in containers.

1. Start it

git clone https://github.com/ksuk/merlon.git
cd merlon
cp .env.example .env
mkdir -p operator-content/tm_scenarios operator-content/screening_lists
cp content/_sample/cdd_weights/funds_transfer.yaml operator-content/cdd_weights.yaml
cp content/_sample/tm_scenarios/*.yaml operator-content/tm_scenarios/
cp deploy/seed/demo/screening_lists/*.yaml operator-content/screening_lists/
docker compose up --build

The standard topology mounts operator-content read-only and requires the native engine. The copied files are synthetic examples for local evaluation; replace them with reviewed, institution-approved policy content before using real data. If the directory or any required root is missing or invalid, the process remains live for setup and diagnostics but GET /healthz/ready returns 503 with "engine":"error", and the system status page marks the engine unavailable.

The first build takes a few minutes. Compose reads .env for the database password, bootstrap token, and development JWT signing secret, so the copy in step two is not optional — without it, startup stops before Merlon can serve the login flow.

The default API host port is 8080. If that port is already in use, choose a different project name and host port before starting the stack:

MERLON_API_HOST_PORT=18050 \
  docker compose -p merlon-local-18050 -f docker-compose.yml up --build

When using an override, replace :8080 with :18050 in the URLs below. The standard topology does not publish PostgreSQL to the host; use the documented test overlay only when a local test client needs a loopback database port.

Wait for this line:

{"level":"INFO","msg":"merlon-api starting","env":"development","mode":"all","addr":":8080"}

2. Create the administrator account

Open http://localhost:8080.

Authentication is enabled in this topology and no account exists yet, so the login screen is a dead end until you create one. Follow Create the administrator account below the login form, or go straight to http://localhost:8080/setup.

Enter an email address and a password of at least 12 characters. This route only works while no account exists — once the first administrator is created it rejects further requests. After signing in, use User management to create the Analyst and Viewer accounts required by your operating model. The same screen changes roles or active state and sets a replacement password. Each of those changes invalidates that account's existing sessions.

:::note healthy does not mean set up

The standard Compose healthcheck asks GET /healthz/ready, so docker ps remains unhealthy until the engine is loaded and the first administrator exists. The process is still reachable through GET /healthz/live for setup and diagnostics. See Troubleshooting.

:::

3. Log in

Log in with the account you just created. You should land on the dashboard, with an empty customer list and no alerts. That is expected: nothing has been loaded yet.

Open User management, create separate Analyst and Viewer accounts, and confirm that each can sign in. Keep at least one active Admin account: the API rejects an attempt to disable or demote the last one.

What next

Goal	Go to
See the product working with data	Demo Tour
Load your own customers and transactions	Initial Migration
Understand what drives scores and alerts	Architecture
Tune the rules	Rule Authoring
Change any setting	Configuration
Run this for real	Deployment
Something did not work	Troubleshooting

Before this leaves your machine

.env.example ships development-only credentials, and every one of them is marked MUST change in production. The compose file used above also publishes port 8080 on all interfaces.

This quick start is for evaluation on a local machine. Read Deployment and Configuration before running Merlon anywhere else — a system that produces regulatory records under default development credentials is not one you want to explain later.