A hosting panel for the AI era: vibe-code it, push to GitHub, it's live.Explore →
DocsUpdating ZoPanel

Updating ZoPanel

Update ZoPanel from the panel or with zopanel update. Every update snapshots the database, checks health and rolls back by itself if needed.

ZoPanel updates itself as one signed binary. Each update is guarded: the panel database is saved first, the new version must pass a health check, and if it does not, the previous version and its database come back automatically. This page covers manual and automatic updates, and how to roll back by hand.

What an update does

  1. Download and verify. The release manifest for your channel is downloaded and its Ed25519 signature checked. The binary must match the SHA-256 in that signed manifest. Unsigned or modified releases are refused.
  2. Keep the previous version. The running binary is copied aside so it can be restored.
  3. Snapshot the database. The panel database is copied consistently to /var/lib/zopanel-root/pre-update/. The last 3 snapshots are kept. If the snapshot fails, the update stops and the services are not restarted on the new version.
  4. Restart on the new version. Both services, zopanel-agent and zopanel, restart. The new version migrates the database on start.
  5. Health check. The guard waits up to 3 minutes for both services to be active, the agent to answer and the panel's health check to pass, then checks again after 20 seconds to make sure it stays up.
  6. Automatic rollback. If the health check fails, the previous binary and the database snapshot are put back, and the services restart on the old version.

The guard runs as its own systemd unit, so a dropped SSH connection or closed browser tab does not stop it halfway. Your websites, databases and mail keep running throughout: only the panel and its agent restart.

Update from the panel

  1. Go to Settings → Updates.
  2. The card shows the Installed version and Latest version. Click Check now to look again.
  3. When a new version is available, its release notes are shown. Click Update now.

The update runs as a task. The panel is unavailable for a few moments while it restarts.

Update from the command line

As root on the server:

zopanel update

It prints each step and ends with ZoPanel X.Y.Z is up and healthy, or with the reason it rolled back. If you are already on the latest version, it says so and does nothing.

To check the installed version:

zopanel version

Automatic updates and channels

In Settings → Updates → Update preferences:

Setting Options Effect
Channel Stable, Beta Which releases the server installs
Automatic updates On / off Installs every new release at 04:00 server time
Install security releases automatically On / off Installs security releases within about an hour, at any time of day

Automatic updates are off until you turn them on. When they are off, the panel checks once a day and sends an Update available alert once per new release.

Security releases

A release whose signed manifest marks it as a security release (or a later release that carries such a fix the server does not have yet) can install by itself, without waiting for 04:00 and without turning on every update:

  • New servers (installed with 0.4.29 or later) have it on. The installer asks once; --no-auto-security-updates (or ZOPANEL_NO_AUTO_SECURITY_UPDATES=1) installs with it off.
  • Servers installed before 0.4.29 keep it off. Full administrators are asked once on the dashboard (Install ZoPanel security releases automatically?, Turn on or No thanks); either answer is kept and can be changed later in Settings → Updates.

When it is on, the panel checks the update server every hour. A security release is installed at the first 15-minute round once it has been known for 15 minutes, so within about an hour of being published. The install is the same guarded update as Update now: the manifest's signature and replay protection are checked again by the root agent, the database is saved, the new version must pass the health check, and a version that does not become healthy is rolled back with its database. It waits while a backup, a restore, an import or an account move runs, and tries at the next round. A download or install that fails is tried again an hour later, at most 3 times per release.

A security release that was rolled back, by the guard or by you with zopanel rollback, is never installed again automatically: install it with Update now once you have looked at why. Settings → Updates shows what is pending (installs within the hour, waiting for a backup, retrying, or not installed automatically and why).

Each step is in the activity log (Started an automatic security update, Security release installed automatically, Automatic security update failed). The Security release installed automatically alert (on by default, also on servers whose alerts were saved before it existed) and Panel update failed or rolled back tell you what happened.

When a newer release is out, full administrators also see it in the panel: ZoPanel X is available in Needs your attention on the dashboard, with the first lines of the release notes, a What's new link to the changelog and an Update button that opens Settings → Updates, and a dot on the Settings menu. A security release is shown as a warning. The panel uses what its last check found (at most every 12 hours, and soon after it starts); opening the dashboard never contacts the update server. Limited administrators, resellers and customers do not see these notices.

Automatic updates use the same guard as manual ones.

Alerts about updates

In Settings → Alerts, turn on these events to be told about updates by Telegram, email or webhook:

  • Panel update failed or rolled back: the new version did not become healthy and was rolled back, or the update failed.
  • Security release installed automatically: a security release was installed by itself and checked healthy (see above).
  • Update available: a new release is out (when automatic updates are off), with the first lines of its notes and the changelog link. On by default on servers installed with 0.4.26 or later; servers installed earlier keep it off until you turn it on.

If the server restarts in the middle of the health check, the panel reports that the update was not checked, and you can decide whether to keep it or roll back.

Roll back by hand

If a new version works but you prefer the previous one, run as root:

zopanel rollback

This puts the previous binary back and restarts the services. What happens to the panel database depends on the situation:

Situation Database
The last update failed less than 30 minutes ago Restored from the snapshot taken before that update
The update succeeded, or the snapshot is older Kept as it is, so changes made since (accounts, websites, mailboxes) are not lost

The command prints which case applies and how old the snapshot is.

--db: also restore the database

zopanel rollback --db

Also restores the database snapshot taken before the last update, whatever its age. Use it when the previous version cannot run on the current database. Everything changed in the panel since that update is lost: accounts, websites, databases, mailboxes and settings created or changed after it. Website files and the contents of customer databases are not part of the panel database, but the panel's records of them are.

--binary-only: never touch the database

zopanel rollback --binary-only

Puts the previous binary back and always keeps the current database.

Rollback fails with no previous version to roll back to if no previous binary is saved, for example right after a fresh installation.

Troubleshooting

Problem What to do
The panel does not open after an update Wait up to 3 minutes for the guard to finish. Then run systemctl status zopanel zopanel-agent and journalctl -u zopanel.
The update rolled back The alert and the task log give the reason. Run zopanel ctl doctor, and send zopanel ctl support-bundle to support if needed.
Websites behave differently after an update Run zopanel ctl rebuild to apply every account and website's configuration again.

Updating the operating system

ZoPanel updates do not upgrade your system packages. The installer turns on automatic security updates (unattended-upgrades). The Security Center on the Security page tells you when security updates are pending or a restart is needed after a kernel update.

PHP updates

PHP comes from its own repository: packages.sury.org on Debian and the ondrej/php PPA on Ubuntu (Ubuntu 26.04 uses the distribution's PHP). The distribution's unattended-upgrades settings only include the distribution, so since 0.4.27 ZoPanel adds PHP's repository in a file of its own, /etc/apt/apt.conf.d/52zopanel-php (origins deb.sury.org and LP-PPA-ondrej-php). It is written on new servers and, on existing ones, once when the agent starts, only if automatic security updates are on and only if the file does not exist yet; 50unattended-upgrades and your own edits are never changed. Delete the file to stop automatic PHP updates: ZoPanel does not write it again unless you press Fix on PHP fixes install automatically in the Security Center. Check with unattended-upgrade --dry-run -d: the allowed origins include origin=deb.sury.org or origin=LP-PPA-ondrej-php.

Installing a fixed PHP package does not restart PHP: every account has its own PHP-FPM master, and so do Adminer and webmail, and a running master keeps the old binary in memory. ZoPanel therefore adds an apt hook (/etc/apt/apt.conf.d/80zopanel-php-restart) and checks every 5 minutes as well: after any PHP upgrade, by unattended-upgrades, by Server → OS updates or by apt by hand, every PHP-FPM master still running a replaced binary is reloaded on the new one (running requests finish) and restarted if a reload is not enough. Stopped pools start on the new binary at the next visit. Each move is recorded in the Activity Log ("Moved PHP to the new build").

When the panel is updated to 0.4.27, the agent installs the fixed PHP builds of the installed PHP versions at once (PHP2Shell, CVE-2026-109618 and CVE-2026-109619, fixed in 8.5.12, 8.4.27, 8.3.36 and 8.2.35): only the php* packages of those versions, nothing else, then the masters move as above. If apt is busy it tries again every 5 minutes.

Docker, MongoDB, .NET, Redis and backports

ZoPanel adds a few more repositories when you install components: Docker's (download.docker.com, on Debian 12), MongoDB's (repo.mongodb.org, one series such as 8.0), Microsoft's for .NET on Debian (packages.microsoft.com), the .NET backports PPA on Ubuntu (ppa:dotnet/backports), Redis' on Ubuntu 22.04 (packages.redis.io) and Debian's backports for the 6.12 kernel on Debian 12 when you choose it. PostgreSQL and MariaDB come from the distribution, which unattended-upgrades already covers. Since 0.4.29:

  • Their fixes install automatically. /etc/apt/apt.conf.d/53zopanel-thirdparty adds their origins to unattended-upgrades (for example origin=Docker,label=Docker CE and origin=mongodb,archive=${distro_codename}/mongodb-org/8.0). It follows the repositories present, is kept when you edit it, and stays deleted if you delete it (until you press Fix in the Security Center). Check with unattended-upgrade --dry-run -d.
  • Never a new major version. /etc/apt/preferences.d/zopanel-majors holds Docker's packages, containerd and Redis at the major version installed (Pin: version 5:29.*, other versions of that repository at priority -1), so Docker 29 gets 29.x fixes but never 30, also for Server → OS updates and apt upgrade. MongoDB's repository is one series (8.0 never offers 8.2), and .NET packages carry their major in their name (dotnet-runtime-8.0). Microsoft's repository only supplies .NET: its other packages get priority 100, so it never replaces a package of the distribution. To move to a new major on purpose, delete the file (it is not written again unless you press Fix), upgrade, and press Fix to hold the new major.
  • Docker restarts without stopping your apps. A Docker upgrade restarts dockerd. ZoPanel's daemon.json has "live-restore": true, so containers keep running (measured on Debian 12 with Docker 29.9.0 → 29.9.2 and containerd 2.4.1 → 2.4.2: the same container processes kept running; their published addresses did not answer for about 2 seconds while dockerd restarted). If your daemon.json has no live-restore, every container would restart, so Docker is kept out of the automatic updates (Package-Blacklist) and the Security Center offers the update with one click instead.
  • Servers come back on the new build. MongoDB's package does not restart mongod after an upgrade, and Debian has no needrestart. After every apt run ZoPanel restarts mongod (and redis-server) if it still runs a replaced binary, and starts again any ZoPanel unit that failed meanwhile; both are recorded in the activity log. On Ubuntu, needrestart restarts most services itself; /etc/needrestart/conf.d/zopanel.conf tells it to leave zopanel and zopanel-agent alone, which ZoPanel restarts itself under its update guard.
  • Security Center. Each repository has a check, No updates waiting from …, listing the packages with a newer build and a Fix that installs them now (only those packages, within the held versions; for Docker it says that apps' addresses pause for a few seconds). Fixes from the repositories ZoPanel added install automatically fails when one of them is left out of the automatic updates.

← Licensing Panel settings →