Upgrades
Upgrading Miabi is intentionally simple: pull a newer image and recreate the containers. Miabi handles the rest on startup.
Automatic migrations
On every startup, Miabi brings the database in line with the running binary:
- Schema migrations are applied automatically (GORM
AutoMigrate). - Ordered data
upgradesteps run in sequence, with each applied step recorded in theupgrade_stepstable so it never runs twice.
Because both happen automatically, upgrading is just a matter of starting the new version. You watch the logs to confirm migrations completed before the instance serves traffic.
Update notifications
Once a day, Miabi reads versions.miabi.io to learn the
latest release of Miabi, the node agent, the runner and the gateway, and shows platform admins a
dismissible notice with a link to the release notes. A release published as a security fix is shown
as a red Security release notice. The check only notifies — nothing upgrades on its own.
An upgrade is always something you ask for, whether by running miabi upgrade (stack) or
bumping the image and running docker compose pull && docker compose up -d (Compose).
The check is channel-aware: a pre-release build is offered newer pre-releases and stable releases; a stable build is never nudged onto a pre-release. Dismissing a notice hides it until the next version appears.
| Variable | Default | Purpose |
|---|---|---|
MIABI_UPDATE_CHECK | true | Set false to disable the check entirely (air-gapped hosts, or to avoid the outbound call) |
Nothing about your install is sent: it is one unauthenticated GET of a static file, identified only
by User-Agent: miabi/<version>, with no install id. (Installation counting is separate: see
Telemetry.) A dev build never checks.
Admins can read the cached result at GET /api/v1/admin/update.
Downgrades are not supported
Miabi rolls forward only. The upgrade_steps table tracks which steps have been applied, and there are no reverse steps — once a migration has run, the previous binary may no longer understand the schema.
MIABI_ALLOW_DOWNGRADE=true exists as an escape hatch, but it does not undo migrations. Only set it if you fully understand the schema implications of running an older binary against an already-migrated database. The supported recovery path for a bad upgrade is to restore the pre-upgrade backup.
Where to go next
- Upgrading — the procedure, for both install methods.
- Backups — take one before every upgrade.
- Configuration — pinning the image version.