Skip to main content
This split deployment example is experimental.
The docker-compose.split.yml example runs Postgres, one control plane, the webapp proxy, and two gateways on one Docker host.
Open localhost:8080 and follow the setup steps. Or use the CLI to set up and verify inference:
Every service and short-lived startup job references AIRMUX_IMAGE, so pin that variable to one published digest for coordinated deployments. The split stack follows the same database and catalog startup sequence as the default stack. Both gateways start after the control plane becomes healthy. The webapp proxy distributes /inf/ requests between them. The same optional Docker configuration directory is mounted in every role. Install the airmux CLI on the machine you use to manage the instance.

Volume ownership

Every additional gateway needs a new persistent state volume.

Multi-host requirements

The checked-in split file demonstrates service boundaries, not a multi-host production topology. Across hosts, provide:
  • Reachable Postgres for the control plane
  • One secret store accessible to both planes, with the control plane able to write and data planes able to read (until we support vaults, we recommend that you use insecure_database)
  • A private authenticated control-plane URL for bundle polling, event ingestion, and heartbeat
  • One persistent cache and outbox directory per gateway
  • A streaming-capable load balancer with response buffering disabled
Set AIRMUX_DATAPLANE_CONTROL_PLANE_URL to the private control-plane address. Protect this path and its data-plane management key. Keep one control-plane replica. Multiple control-plane replicas isn’t supported right now. Do not use docker compose --scale for gateways. Each gateway needs an explicit service and its own identity, bundle cache, and usage outbox volume.

Upgrade and roll back

Use one release digest for every role. Read its release notes, compare any custom runtime YAML with the new image, and back up Postgres, runtime-credentials, provider-secrets, and every gateway state volume together. A database migration may prevent the previous image from starting, so record the current digest and confirm the backup can be restored. Remove gateways from public traffic and let active streams finish. Use the target release’s split and base Compose files, set AIRMUX_IMAGE to the target digest, then run:
Wait for the control plane and both gateways to report ready, then restore traffic and check a buffered request, a streaming request, and usage export. If verification fails after migration, stop the new stack, restore Postgres and all state volumes from the same recovery point, and redeploy the previous digest. Do not run the previous image on the migrated database.

Move from airmux to split

The default and split Compose files use different named volumes. Migration requires a database dump plus a stopped copy of /state/runtime, /state/secrets, and one gateway’s /state/data-plane. Restore each into the corresponding split volume before the first split startup.