Getting started
Configure the shared services
Section titled “Configure the shared services”-
Copy
config.example.tomltoconfig.tomland.env.exampleto.env. -
Set
MONGO_URIto an existing MongoDB instance reachable from the containers. All services use the top-level TOMLdatabase. -
Generate a Fernet key and set
OMSBRIDGE_ENCRYPTION_KEY:Terminal window uv run python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())" -
Configure a CAPTCHA solver in TOML and supply its token through the named environment variable before provisioning broker accounts.
-
Set
MARKET_DATA_API_KEYfor the supplier. Updates and session maintenance do not require this serving key.
Keep the encryption key with your MongoDB backups. Credentials and reusable
sessions cannot be recovered without it. The environment MongoDB URI overrides
mongo_uri in TOML; an empty environment override is rejected.
Start Bridge and provision accounts
Section titled “Start Bridge and provision accounts”docker build --secret id=speculum_username,env=SPECULUM_USERNAME --secret id=speculum_token,env=SPECULUM_TOKEN -t market-gateway:local .docker compose up -d --no-build bridge session-maintenancedocker compose exec bridge python -m omsbridge.clients create nonameThe client command prints a bearer token. Connect through a TLS-terminating gRPC
proxy, or directly over a trusted backend network, then use Accounts.CreateAccount
to provision broker credentials. See clients and accounts.
The main Compose file does not publish the gRPC ports on the host. Configure proxy
routes to bridge:8080 and market-data:8080, or add explicit local port mappings
for host clients.
Populate the catalogue and start Market Data
Section titled “Populate the catalogue and start Market Data”docker compose run --rm --no-deps market-data -m marketdata.update --config /etc/omsbridge/config.tomldocker compose up -d market-dataInspect the update results before starting the supplier: an empty catalogue prevents serving. Stock updates require an enabled Ephoenix account. Live commodity feeds require an enabled OMEX account; the public OMEX catalogue updater needs no login.
Schedule the update command daily. It continues independent jobs after a failure and exits nonzero if any job fails. Restart the supplier after updates to load new instruments immediately.
Run a host process
Section titled “Run a host process”The repository runs from source with uv. Set PYTHONPATH=src in .env, then run:
uv run --env-file .env python -m omsbridge.server --config config.tomluv run --env-file .env python -m omsbridge.session_maintenance --config config.tomluv run --env-file .env python -m marketdata.update --config config.tomluv run --env-file .env python -m marketdata --config config.tomlRun each long-lived service in its own terminal or process manager. Configure writable cache, snapshot and spool paths when running outside Docker.
Build registry credentials
Section titled “Build registry credentials”The shared Python image uses Speculum as its package index.
Export SPECULUM_USERNAME and SPECULUM_TOKEN before running the build command;
the Dockerfile receives them as required BuildKit secrets. These are separate
from broker and API credentials. Compose starts the prebuilt image.
The documentation image uses Speculum’s npm registry at build time and receives
SPECULUM_TOKEN through the speculum_token BuildKit secret. It needs no
application secrets or database. See the repository’s docs/README.md for its commands.