Skip to main content
Docker Compose runs airmux and Postgres. The CLI is available inside the app container.

Start

Follow the quickstart to download the release’s Compose file and start the stack:
Compose creates airmux-config automatically. The stack uses the bundled configuration until you add a custom YAML file. If you need to customize the deployment see Customize the runtime YAML.

Configure the public origin

For another local port:
Set these in .env and restart Compose. For a public deployment, terminate TLS at a reverse proxy and set AIRMUX_PUBLIC_URL to the exact HTTPS origin. Once your deployment is available, open its URL in a browser and follow the setup steps. Or set up the instance through the CLI using the same URL:
Set a URL-safe POSTGRES_PASSWORD before the first start of a public installation. Changing the Compose variable later does not rotate the password already stored by Postgres.

Customize the runtime YAML

Use this when you need to change the control-plane or data-plane settings in the configuration reference. If Docker created airmux-config as root on Linux, first take ownership with sudo chown "$(id -u):$(id -g)" airmux-config. Copy the default YAML from your running image:
Edit airmux-config/airmux.yml. Keep its /state paths unless you also provide suitable persistent storage, and keep the control plane and data plane on the same secret store. The Compose file mounts ./airmux-config read-only and any change to airmux.yml will be picked up when you restart the stack. If the file is absent or empty, it will use the default YAML bundled in the image. Runtime ${env:...} references use each container’s environment, not values read directly from .env. Paths in the custom YAML resolve relative to /config, so use absolute /state/... paths for persistent data as the bundled file does. Compare your custom file with the new image’s default YAML when upgrading. Restart the stack after editing the YAML:
If startup fails, inspect docker compose logs migrate taxonomy app. To return to the image default, remove airmux-config/airmux.yml and run the same two commands.

Startup and database changes

docker compose up runs the migration job first and the catalog job second. The app container starts only after both jobs succeed. On later runs, migration checks the current schema revision and the catalog job reapplies the definitions shipped with the selected image. To diagnose a failure:

State

docker compose down preserves both volumes. docker compose down -v deletes the complete installation.
Back up both volumes before an update, and do not use down -v unless permanent deletion is intended.

Upgrade and roll back

Read the target release notes and compare any custom runtime YAML with the target image’s default. Record the current image digest, stop new traffic, and back up Postgres and /state together. The migration job may change the database schema and an older image cannot safely use a database migrated by a newer release. Download the Compose file for the target release. Remove any older AIRMUX_IMAGE override from .env, then replace the stack:
The application service is named app. --remove-orphans removes the previous cli service when upgrading from an older Compose file, freeing its port for app. Keep the same Compose project name and directory to reuse the existing database and application volumes. Check /healthz on the public origin, run docker compose exec app airmux doctor, and send a buffered and streaming request. Confirm that the requests appear in usage. If verification fails after migration, stop the new stack, restore Postgres and /state from the same backup, and redeploy the recorded previous release. Do not roll back only the image against the newer database.