Run and configure services
Processes
Section titled “Processes”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.
Configuration
Section titled “Configuration”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.
Persistence and schedules
Section titled “Persistence and schedules”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.
Network and deployment
Section titled “Network and deployment”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.
Documentation server
Section titled “Documentation server”The documentation stack is independent of the application services:
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-buildThis 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.