Skip to content

Run and configure services

The application image uses python as its entrypoint. Each process uses the same TOML configuration and MongoDB database:

Command after python Responsibility
-m omsbridge.server --config config.toml Bridge gRPC, order recovery and trading workers
-m omsbridge.session_maintenance --config config.toml Scheduled session maintenance
-m marketdata --config config.toml Market Data gRPC and direct broker feeds
-m marketdata.update --config config.toml One-shot updates and quarantined-instrument recovery

Run one Bridge and one supplier per database. The updater uses a renewable global lease to prevent overlapping complete updates. Schedule the update command daily; there is no additional update scheduler.

Use config.example.toml and .env.example as the complete configuration examples.

Setting Purpose
MONGO_URI Shared MongoDB URI; overrides root TOML mongo_uri
OMSBRIDGE_ENCRYPTION_KEY Fernet key for broker credentials, sessions and client tokens
MARKET_DATA_API_KEY Required API key for the supplier
OMSBRIDGE_CLICKHOUSE_URI Optional HTTP(S) recording destination; overrides root clickhouse_uri
MARKET_DATA_FAKE_ENABLED Enable synthetic supplier feeds
database Single MongoDB database name, default omsbridge
market_data.snapshot_interval Snapshot interval, default one second
market_data.dataframe_max_limits_rows Stored book depth, default five

An empty MongoDB or ClickHouse URI environment override is rejected. ClickHouse recording is disabled when neither its environment variable nor its root TOML setting exists. Remove the former market_data.clickhouse_connection_string_env setting when upgrading.

When upgrading, remove market_data.api_key_env from TOML and set MARKET_DATA_API_KEY in the supplier’s environment.

Compose persists /var/lib/omsbridge for quote cache and recording spool replay. Keep cache, snapshot and spool paths writable for the supplier. MongoDB is external to Compose and owns accounts, sessions, client identities, instruments, holidays, daily history, subscription health and managed-order journals.

Daily collection runs at 18:10 Asia/Tehran and upserts instrument_daily. Catalogue and holiday updates run only through the explicit update command. Supplier startup does not run them. An empty catalogue prevents serving.

Optional ClickHouse recording uses base_market_data_snapshots and option_market_data_snapshots. It is an external recording destination, separate from MongoDB. Inspect spool and recording logs when this destination is unavailable.

Back up MongoDB together with the encryption key. Retain orders and order_operations: their deletion also removes duplicate protection.

Both gRPC servers default to 0.0.0.0:8080 and accept --address HOST:PORT. If you run both directly on one host, give one a different port. When upgrading, remove the root address and [market_data] address keys from config.toml and pass custom values with --address on the corresponding server commands. In Shipyard, set the flag in the service’s Compose command and point its gRPC route at the configured container port.

HAProxy terminates TLS and forwards cleartext HTTP/2 (h2c) to Bridge. Configure separate routes for bridge:8080 and market-data:8080. The application Compose file does not publish either gRPC port on the host.

In Shipyard, store MongoDB, encryption and API credentials as secret runtime variables. The Bridge client CLI can run inside the Bridge container. Remove old TOML [clients.*] sections; clients are managed in MongoDB.

The documentation stack is independent of the application services:

Terminal window
docker build -f docs/Dockerfile --secret id=speculum_token,env=SPECULUM_TOKEN -t market-gateway-docs:local .
docker compose -f docs/compose.yaml up -d --no-build

This serves the built Starlight site on http://127.0.0.1:8080. Node builds the site; the final container runs BusyBox httpd as an unprivileged user on a read-only filesystem. Installation uses Speculum’s npm registry with SPECULUM_TOKEN passed as a BuildKit secret from the build client’s environment. It needs no application runtime environment variables, database or volume. In Shipyard, build docs/Dockerfile from the repository root and route HTTP to container port 8000. TLS and any reader access restrictions belong at the existing proxy.