Skip to main content
airmux is pre-1.0. It does not promise cross-version compatibility between the control plane, gateways, configuration, or database schema. Use the same release for every component unless its release notes explicitly document a rolling-compatible path.
The Compose migration job applies the forward database migration before starting the new release. The CLI has no operator-facing downgrade command. Do not run an older release against a database migrated by a newer release.

​
Prepare a recovery point

Before replacing any process:
  1. Read the target release notes and configuration changes
  2. Record the current release or image digest
  3. Stop new inference traffic and allow active streams to finish
  4. Back up Postgres, runtime credentials, provider secrets, and every gateway state directory together
  5. Confirm that the database backup and state snapshot can be restored on isolated infrastructure
Include each gateway’s identity, accepted bundle, and SQLite usage outbox in the state snapshot. Restoring only the database or only /state can leave credential metadata, secret values, bundles, and pending usage out of sync. Set AIRMUX_IMAGE to the target ghcr.io/michel-tricot/airmux digest before replacing either topology.

​
Upgrade the full platform

Follow the Docker Compose replacement procedure. Preserve the public origin, database, and state mounts. Run the documented docker compose up -d --wait command. Compose completes the migration and catalog jobs before it replaces the serving stack. For a split deployment:
  1. Remove every gateway from public traffic and stop it after active streams finish
  2. Set AIRMUX_IMAGE to the new digest and run docker compose -p airmux-split -f docker-compose.split.yml up -d --wait; Compose runs the migration and catalog jobs before replacing the services
  3. Wait for the control plane health check and each gateway’s /readyz response before restoring traffic

​
Verify the release

Check the public route and management context:
Send one buffered request and one streaming request. Confirm that the requests appear in airmux events list, then verify that airmux_data_plane_metering_outbox_pending and airmux_data_plane_metering_outbox_oldest_age_seconds return to their normal ranges on the internal metrics listener.

​
Roll back

After a failed post-migration verification:
  1. Stop the new release and all inference traffic
  2. Restore Postgres and every state directory from the same recovery point
  3. Redeploy the recorded previous release
  4. Repeat the health, readiness, buffered, streaming, and usage checks
Do not roll back only the application against the newer database schema. Use a forward fix without restoration only when the newer release notes explicitly say the database and bundle contracts remain compatible.

​
Upgrade a gateway-only installation

Back up the standalone directory, replace the installed tool, and validate before serving:
Before removing the backup, make a real buffered and streaming request. To roll back, reinstall the previous package version and restore its matching standalone directory.