Updates and upgrades
MonoPbx checks by itself whether a newer release is available, and on most installs you can upgrade with one button. This page says what the check does, what the button does, and what to run by hand when there is no button.
Seeing whether an update is available
Open System, Upgrades (/admin/upgrades, system administrators). The Software update card says one of:
- Up to date (1.2.0).
- Version 1.3.0 is available (installed: 1.2.0). with a Release notes link.
- The update check is off. (see "Air-gapped installs" below).
- A short reason when the release channel could not be reached.
The PBX looks once a day, and Check now looks straight away. A check only reads a small public file (release.json) from the release channel. It installs nothing and sends nothing about your installation or your calls. While a newer release is available, the Upgrades entry in the console menu shows an Update badge.
The channel (stable, beta or nightly) is the one the install was made from.
A nightly build shows its version and its build together, for example Version 1.0.0 · build 19 Nov 2026 (36e9e95): the date it was built and the first characters of its build number. What's new lists one entry per nightly, and all entries in one language: your console language when every entry has been translated, otherwise English for all.
Upgrading with one click
Press Upgrade now. The window tells you what will happen:
- A full backup (a snapshot) is taken first, so you can always go back.
- The new release is downloaded, checked and started, and it must pass its self-test.
- If the self-test fails, MonoPbx returns to the old release by itself, with the data from before the upgrade.
The PBX is offline for a few minutes and calls in progress end, so choose a quiet time. On an installation with call hand-over turned on (MPBX_SIP_HANDOVER=true), ordinary answered calls stay up through the restart instead; a call that was being recorded keeps being recorded and then shows as two recordings, one from before the restart and one from after. The console goes offline while it restarts; the page keeps asking and shows the steps: requested, downloading, checking, taking the backup, installing, starting and updating the data, self-test. When it ends you see one of three results:
| Result | Meaning |
|---|---|
| Upgraded to 1.3.0 | The new release is running and passed its self-test. |
| The upgrade did not pass its self-test | The old release is running again with the data from before the upgrade. Nothing is lost. Ask support, with the support bundle, before trying again. |
| The upgrade did not complete | The reason is shown. If it says nothing was changed, the old release is still running. |
You need the permission system.operations:write (System Owner). Every request is recorded in the audit log (upgrade.requested). After a successful upgrade the snapshot stays, so Roll back on the same page is still available.
The upgrade log
Under the steps, both in the update window (Check for updates) and on the Upgrades page, Show log opens the full output of the upgrade the update agent just ran: the download, the backup, the start, the self-test and, when it happened, the rollback. While the upgrade runs the log follows the end and refreshes every few seconds (and stops when the run ends). If the upgrade failed or was rolled back, the log opens by itself and the first failing line (a line that starts with FAIL, or mpbx-ctl: ... FAILED) is shown highlighted above it, so you can see what went wrong without logging in to the server. Download log saves it as mpbx-upgrade-<UTC time>.log; attach that file when you ask support for help.
The log is shown as plain text: terminal colour codes are removed, anything that looks like a secret (password=, token:, Bearer ..., the password of a URL, a private key block) is replaced by [redacted], and only the last 2 MiB are shown. The update agent keeps the logs of the last ten runs before it (ctl/state/upgrade-<UTC time>.log next to the current upgrade.log); they are listed under Earlier upgrades, each with a download link. Reading the logs needs system.settings:read, like the Upgrades page.
For scripts: GET /api/v1/system/upgrades/log returns the current log as text/plain (?name=upgrade-<UTC time>.log for an earlier one, ?download=1 for a file download) and GET /api/v1/system/upgrades/logs lists them.
When there is no button
The button is shown only when the release may be installed directly (at most two releases behind, same channel, no declared breaking change) and this install can upgrade itself. Otherwise the page shows Update from the server's command line: a short explanation, a Copy update command button, a link to this page and, under Show the command, the exact command. It says why the console cannot do it itself:
| Your install | One-click upgrade | What to run |
|---|---|---|
| VM installer or Debian package | Yes. The installer starts the update agent (the mpbx-updater container) by default; an install made before that gets it with sudo mpbx-ctl updater enable (the next apt-get upgrade or sudo monopbx upgrade does it too). | sudo mpbx-ctl upgrade --channel stable |
| Docker Compose (your own checkout) | Yes, once the mpbx-updater service is on: see "The update agent" below. | sudo mpbx-ctl upgrade --channel nightly, or the command shown on the page. |
| Kubernetes | No | deploy/k8s/scripts/upgrade.sh upgrade --overlay overlays/YOUR-OVERLAY --release release.json; the page shows the full line, including the download of release.json. |
A release that needs your decision (a breaking change, more than two releases, another channel) is shown with its reasons and is never started from the console. Read its release notes, then upgrade from the command line with the option the notes name.
The update agent
The button only asks. The API container has no access to Docker, so it writes a signed, single-use request into the install's ctl/requests directory, and the update agent carries it out: the mpbx-updater service of the Compose stack. It runs as root with the Docker socket (the same power as running mpbx-ctl yourself), checks the signature, age and release again, then runs the usual upgrade: snapshot with a full backup, new images, restart of the application services, self-test, automatic rollback. It never stops or restarts itself during an upgrade; a newer updater image is applied afterwards (sudo mpbx-ctl updater enable, or docker compose up -d mpbx-updater). The Upgrades page shows Install update while the agent runs.
The installers (Debian package, install.sh) turn it on by default. On a Compose install of your own, from the install directory (.env holds the image names):
sudo mpbx-ctl updater enable # records the paths in .env, adds the `updater` profile, starts only that service
or by hand: set MPBX_CTL_PROD (the install directory, as it is on the host), MPBX_CTL_ROOT (a directory for snapshots and state), MPBX_CTL_COMPOSE_FILES, MPBX_CTL_MODE=images, MPBX_CTL_CHANNEL in .env, add updater to COMPOSE_PROFILES, and run docker compose up -d mpbx-updater with your usual -f files. The image is ghcr.io/ilinaya/monopbx-updater. Do not also run the older systemd units (install-host-agent.sh): updater enable switches them off.
What an upgrade installs
On a VM installer or Debian package install (the files live in /opt/mpbx), an upgrade from the console or with sudo mpbx-ctl upgrade --channel ... installs the whole release, not only its container images:
- the new images, pinned by digest;
- the release's Compose files and the configuration files they mount (for example
clickhouse/config.d/), in/opt/mpbx/compose/prod; - the update agent itself (
/opt/mpbx/bin/mpbx-ctl) and, for installs that use them, its systemd units.
The release channel publishes these files as one archive and names it, with its SHA-256 checksum, in release.json. The update agent downloads it, refuses it when the checksum (or, once the host has a signing key, the signature) does not match, and then lets the new release's agent carry out the rest of the upgrade. So fixes to the upgrade procedure itself apply from the first upgrade that brings them; you do not need apt-get upgrade for that.
What is kept:
.env(your settings and secrets) and the files the installer writes (tls.env,front.env,airgap.env); new image references and any new secrets the release needs are added to.env.- Files you added yourself in the install directory. Files that ship with the release are replaced, so put your own changes in
.envor in a file of your own, not in a file of the release.
The snapshot taken before the upgrade holds the previous files and agent. If the new files cannot be written, the previous ones are put back and the old release starts again; if the new release fails its self-test, the automatic rollback restores them with the data.
Signing key. When a release carries the vendor's bundle signing key, the host keeps it (/opt/mpbx/bundle-signing.pub.pem) on its next upgrade. From then on a release from the channel must be signed with that key, or it is refused and nothing changes. A bundle you copy over by hand (sudo mpbx-ctl upgrade <mpbx-bundle.tar.gz>) is checked against its SHA256SUMS, and against the key when a .sig file lies next to it.
Compose installs of your own. A Docker Compose checkout run with your own files (MPBX_CTL_MODE=images, as install-host-agent.sh and the manual updater setup above set it), or any install whose project directory is not /opt/mpbx/compose/prod, keeps getting the images only: its Compose files are yours and are never replaced. Update them from your checkout when the release notes ask for it.
Air-gapped installs
From the console. On an install whose update agent serves console requests (the VM installer and the Compose bundle with the updater), Admin console, Upgrades has an Update check settings form under the Software update card. Tick or untick Check for new releases every day, enter the Release channel address of your own copy (leave it empty for the public channel) and pick the Release channel, then choose Save settings. The change is handed to the server's update agent, which writes it into the install's .env file and publishes it back; the PBX applies it within a few seconds and needs no restart. Only a System Owner can save the form, and each change is recorded in the audit log. When you switch the check off the page says The update check is off and nothing leaves the host. The address must start with https:// (http:// is accepted only for a copy on the same machine). While an upgrade or rollback waits or runs, saving is refused until it finishes.
On an install without the update agent (Kubernetes, a Compose bundle run by hand) the same form is shown and the settings are kept in the PBX database; saving applies them at once. A setting that the server's environment sets (MPBX_UPDATE_CHECK, MPBX_UPDATE_BASE_URL or MPBX_UPDATE_CHANNEL, see below) always wins: the form shows that field disabled with a note, and you change it by removing the variable from the server's configuration.
An install without internet access can also switch the check off by hand: set MPBX_UPDATE_CHECK=off in the install's .env file (VM installer: /opt/mpbx/compose/prod/.env) and run sudo mpbx-ctl up; on Kubernetes set it as an environment variable of the mpbx-api Deployment. The page then says The update check is off and nothing leaves the host. Upgrade such an install from a bundle you copied over: sudo mpbx-ctl upgrade <mpbx-bundle.tar.gz>.
If you host a copy of the release channel inside your network, set MPBX_UPDATE_BASE_URL to its address (https://...) and, if needed, MPBX_UPDATE_CHANNEL.
Scheduled upgrades
To have the install upgrade itself in a maintenance window, see "Scheduled automatic upgrades" in the upgrade guide (mpbx-ctl auto-update). The Upgrades page shows its schedule and how the last run ended.
Rolling back
Before every upgrade the host keeps a snapshot. Roll back (same page) puts back the release and the data of a snapshot; you type the snapshot id to confirm. Everything written since leaves the running system but is kept in the databases the rollback renames; nothing is dropped.
When the console cannot start a rollback (the update agent of the server has not reported yet, for example on an install without the agent), the Upgrades page says so and links here, under How to update your server. On such an install the rollback runs on the server with sudo mpbx-ctl rollback, which restores the same snapshot.
Updates in the MonoPhone app
System administrators can also follow updates from the MonoPhone app: Settings, Admin, PBX updates. The screen shows the same information as the console's Upgrades page:
- The installed version, the date it was released (or, for a nightly build, the date it was built and its build number) and the update channel.
- Whether a newer version is available, with Check for updates to ask the release channel straight away.
- What's new: the release notes of every version between the installed one and the newest, grouped as New, Improved, Fixed and Security, the same notes the console shows before an update.
- Install update, when the console would offer Upgrade now. The app first asks you to confirm and says what happens (the backup, the self-test, a few minutes offline, calls in progress end). While the update runs, the screen shows its steps and keeps checking while the PBX restarts. Afterwards it shows Updated to 1.3.0: what's new with the notes of the new version, or the reason when the update did not complete.
Pull the screen down to refresh it. Seeing the screen needs system.settings:read; checking the channel and installing need system.operations:write, like in the console. Without that permission the screen is view only. When a release cannot be installed from the app (it needs a decision, or this install cannot upgrade itself), the screen says why and shows the command to run on the server. If the PBX is too old for this screen, the app says Needs a newer PBX: update it once from the console, and the screen works from then on.