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.
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. Install the airmux CLI on the machine you use to manage the instance.

​
Volume ownership

Every additional gateway needs a new persistent state volume. Sharing one SQLite outbox or cloning a running gateway identity is invalid.

​
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
  • 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 remain unsupported until initialization, asynchronous bundle publication, and replica behavior are proven. Do not use docker compose --scale for gateways. Each gateway needs an explicit service and its own identity, bundle cache, and usage outbox volume.

​
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.
Do not start the split stack against a partial copy. Database metadata and provider secrets must move together.