docker-compose.split.yml example runs Postgres, one control plane, the webapp proxy, and two gateways on one Docker host.
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
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:
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.