Skip to content

Getting started

  1. Copy config.example.toml to config.toml and .env.example to .env.

  2. Set MONGO_URI to an existing MongoDB instance reachable from the containers. All services use the top-level TOML database.

  3. 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())"
  4. Configure a CAPTCHA solver in TOML and supply its token through the named environment variable before provisioning broker accounts.

  5. Set MARKET_DATA_API_KEY for 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.

Terminal window
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-maintenance
docker compose exec bridge python -m omsbridge.clients create noname

The 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”
Terminal window
docker compose run --rm --no-deps market-data -m marketdata.update --config /etc/omsbridge/config.toml
docker compose up -d market-data

Inspect 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.

The repository runs from source with uv. Set PYTHONPATH=src in .env, then run:

Terminal window
uv run --env-file .env python -m omsbridge.server --config config.toml
uv run --env-file .env python -m omsbridge.session_maintenance --config config.toml
uv run --env-file .env python -m marketdata.update --config config.toml
uv run --env-file .env python -m marketdata --config config.toml

Run each long-lived service in its own terminal or process manager. Configure writable cache, snapshot and spool paths when running outside Docker.

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.