Quick start

Prerequisites

• Linux, writable /dev/shm, and at least 8 GB of available RAM.
• Java 21, Maven 3.9+, Go 1.25+, Node 22.22+, npm, Git and Python 3.
• Docker for the dedicated PostgreSQL 16 + TimescaleDB container below, and the psql client on your host.
• A separate development machine or VM: the demo uses development authentication. The OMS and market server may listen on network interfaces; do not expose these ports publicly.

Allow Aeron enough socket buffer space on this local machine:

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

1 · Build from source

Download and inspect the Python launcher, then build into a new directory. The first build downloads dependencies and can take several minutes.

curl -fSLo quickstart.py https://openexchange.dev/quickstart.py
python3 quickstart.py build --directory openexchange-local

The launcher checks out match, oms, assets, admin, trading-ui and their shared build dependency cluster-kit. It builds into its own Maven repository; GitHub Packages credentials are not needed. Existing directories are never overwritten.

The admin gateway is built for further operations work but does not supervise this portable demo. Its process catalog has host-specific settings; see the admin setup guide before using it on your machine.

2 · Prepare PostgreSQL

The market gateway requires TimescaleDB. Use this disposable, localhost-only container, separate from any existing database. Choose a demo password when prompted. Its local administrator creates the two randomly named databases and enables the extension; the launcher removes only those databases after stopping.

read -rsp 'Demo database password: ' PGPASSWORD; echo
export PGPASSWORD
export POSTGRES_PASSWORD="$PGPASSWORD"
docker run --rm -d --name openexchange-quickstart-db \
  -p 127.0.0.1:5433:5432 -e POSTGRES_PASSWORD \
  timescale/timescaledb:2.30.0-pg16
export PGUSER=postgres
export PGHOST=127.0.0.1
export PGPORT=5433
until psql -d postgres -c 'SELECT 1' >/dev/null 2>&1; do sleep 1; done

The TimescaleDB image is also used by this guide’s CI check. If the readiness command keeps waiting, inspect docker logs openexchange-quickstart-db in another terminal; do not continue until the database is ready.

3 · Run and verify

python3 quickstart.py start --directory openexchange-local

Wait for QUICKSTART PASS. The launcher checks cluster connectivity, submits crossing limit orders, and verifies executions, settled balances and positions. Then open http://127.0.0.1:5173. The UI uses the seeded local demo account, dev:1.

In a second terminal, this request must return clusterConnected: true:

curl -fsS http://127.0.0.1:8080/api/v1/health | python3 -m json.tool

Press Ctrl+C in the launcher terminal to stop its processes. Logs remain under openexchange-local/runtime-*/logs. A new start creates a new demo; this is not a restart or recovery procedure.

For the same pass/fail acceptance check with automatic shutdown:

python3 quickstart.py start --directory openexchange-local --check

When finished with the demo, stop its disposable database container:

docker stop openexchange-quickstart-db

What this demo proves

A working build, a connected three-node matching cluster, and a completed order-to-settlement path. Shared threads and small buffers keep this local exercise modest. It is not a throughput benchmark or an HA deployment: all nodes share one host and the Assets Engine has one node.

For the separate leader-loss and ledger-conservation acceptance test, use the OMS failover E2E guide. Compare production tuning and measurement conditions in Benchmarks.

Troubleshooting

• Directory already exists: choose a new directory for the build; the launcher preserves existing work.
• Port busy: use an idle development machine or VM. The demo needs 8080, 8081, 5173 and its reserved 9000–9599 and 19000–19599 ranges. The database container uses localhost:5433.
• Database connection fails: check the demo container, PGUSER, PGPASSWORD, PGHOST and PGPORT. Plain PostgreSQL without TimescaleDB cannot start the market gateway. A failed database setup stops startup.
• Election or settlement timeout: check the runtime logs, socket buffers, available memory and CPU contention. Do not interpret a failed verification as a running exchange.