Quick start

Prerequisites

• Linux with a writable /dev/shm (the cluster's fast path lives there)
• Java 21 and Maven 3.9+ (cluster and OMS)
• Go 1.23+ (admin gateway)
• PostgreSQL 14+ running locally, with the psql client
• Redis 7 (optional: without it the OMS falls back to in-memory)
• Node 22 (only for the trading UI)

One system setting first. Aeron's replay channels need bigger socket buffers, and elections hang without them:

sudo sysctl -w net.core.rmem_max=16777216 net.core.wmem_max=16777216

1 · Clone (layout matters)

The five repos must sit side by side with these exact directory names; the admin gateway finds its siblings by layout. Note that the oms repo is cloned into a directory called order-management:

mkdir openexchange && cd openexchange
git clone https://github.com/openexch/match.git
git clone https://github.com/openexch/oms.git order-management
git clone https://github.com/openexch/assets.git
git clone https://github.com/openexch/admin-gateway.git
git clone https://github.com/openexch/trading-ui.git

(If you deviate, set MATCH_PROJECT_DIR and OMS_PROJECT_DIR; see configuration.)

2 · Build

match and the Assets Engine modules are installed to your local Maven repository (not just packaged) because the OMS depends on match-common and theassets-common/assets-cluster modules, none of which are on Maven Central:

(cd match && mvn -B clean install -DskipTests)
(cd assets && mvn -B install -DskipTests -pl assets-common,assets-cluster -am)
(cd order-management && mvn -B clean package -DskipTests \
  && cp oms-app/target/oms-app-1.0-SNAPSHOT.jar oms-app/target/oms-app.jar)
(cd admin-gateway && go build -o admin-gateway .)

3 · Database

The OMS does not create its own schema. Apply it once; without a reachable PostgreSQL the OMS still runs, but in-memory only (nothing survives a restart):

sudo -u postgres psql -c "CREATE ROLE oms LOGIN PASSWORD 'oms-dev'" || true
sudo -u postgres createdb -O oms oms || true
PGPASSWORD=oms-dev psql -h localhost -U oms -d oms -v ON_ERROR_STOP=1 \
  -f order-management/oms-persistence/src/main/resources/db/migration/V001__init_schema.sql

4 · Start the stack

The admin gateway starts and supervises everything else. Its child processes inherit this environment; dev auth mode is for local evaluation only:

cd admin-gateway
export OMS_POSTGRES_PASSWORD=oms-dev
export OMS_AUTH_MODE=dev
nohup ./admin-gateway > admin.log 2>&1 &
sleep 2
curl -X POST http://localhost:8082/api/admin/processes/start-all

5 · Verify

# One node should be LEADER, all three healthy:
curl -s http://localhost:8082/api/admin/status | python3 -m json.tool | head -40

# The OMS is up and connected to the cluster:
curl -s http://localhost:8080/api/v1/health

For persistence, look for PostgreSQL persistence initialized in ~/.local/log/cluster/oms.log.

6 · Trading UI

cd trading-ui
npm ci
npm run dev -- --port 5173
# open http://localhost:5173

The dev server proxies /api/v1 to the OMS (8080), /ws to market data (8081), and /api/admin to the admin gateway (8082). The default dev token matches OMS_AUTH_MODE=dev. Place a limit order on one of the demo markets and watch it hit the book.

Troubleshooting

• Elections hang, logs say "log replication has not progressed": the sysctl from the prerequisites was skipped or didn't persist across a reboot.
• OMS runs but nothing persists: wrong PostgreSQL credentials or the schema wasn't applied; the OMS deliberately degrades to in-memory instead of failing.
• Everything rejected with 401: the shipped default is api-key mode with no keys, which rejects everything. This guide uses dev mode; real modes are in security.
• Ports: the stack claims 8080 (OMS), 8081 (market WS), 8082 (admin), 9000+ (cluster), 9090 (gRPC), 9091/9093 (egress), 9500+ (metrics).

The canonical, always-current version of this guide lives in the match repo: docs/QUICKSTART.md.