Panel updates

#Where updates are managed

Panel updates live on the bipanel tab of Server Admin → System → Updates. The Operating system tab on the same screen updates distribution packages; that topic is covered on the automatic security updates page.

The top of the tab shows the installed version, the channel, how long the installed version is supported, the installation type and when updates were last checked. The panel checks for new versions on its own every 6 hours; Check now asks right away. When a new version is available it is shown with its release notes, and any other versions between yours and the newest appear under Versions in between (the newest one includes all of them). Every version installed from the panel is recorded in Update history with who started it (Automatic / Administrator) and the result. Release notes for every version are also published on the changelog.

On a server installation you can do the same from the command line:

$ bipanel update status
$ bipanel update check
$ bipanel update apply

bipanel update apply waits until the new version is up and the result is recorded (up to 30 minutes).

#Release channels

A server receives releases published to its own channel and to every more conservative channel. For example, a server on release also gets stable and lts releases. Over time, releases move to more conservative channels (release → stable → lts), and pre-releases (such as 1.5.0-beta.1) are only published to current and edge.

Support is counted from the date a release entered the channel, and the panel shows "Supported until at least …" for the installed version and for a new one. The old beta channel name is accepted as current.

#Changing the channel

Pick the channel in the Release channel section and click Save; the panel asks about the new channel at its next scheduled check, within 15 minutes. Changing the channel never downgrades: if you move to a more conservative channel, the installed version stays, and no new update is offered until that channel moves past it.

You can also choose the channel at install time. Without the BIPANEL_CHANNEL environment variable, the installer uses stable:

$ curl -fsSL https://bipanel.io/install.sh | sudo BIPANEL_CHANNEL=lts bash -s -- --hostname server.example.com --email [email protected]

On a container installation, add the same variable to the container's environment. The channel chosen at install time applies until you save a channel on the Updates screen.

#Pinning a version series

Turn on Pin to a version series and enter a value such as 1.4 in Series, and only versions in that series (1.4.x) or older series are offered; 1.5.0 is not. To move to a newer series, raise the series or remove the pin. You cannot pick a series older than the installed one, because versions are never downgraded.

Pinning also helps when a release can only be installed from a certain intermediate version onwards. If a release requires a minimum starting version and yours is older, the panel shows Update to … first and does not install that release. Pin to the intermediate version's series, install it, then remove the pin.

#Automatic update modes

Choose the general mode in the Automatic updates section; the default is Notify only.

Pre-releases only install themselves in Install all releases mode. The other settings:

• Rule by channel: you can set a separate rule for releases published to a given channel (for example, install patches for stable releases and only notify for current ones). Channels without a rule use the general mode. Apply the recommended rules fills in the recommendations from the table above.
• Maintenance window (server time): automatic installs only happen during these hours, 03:00–05:00 by default. If the start and end are the same, any time of day is allowed.
• Back up the panel database before updating: on by default. This backup is restored during a rollback, and the last 5 backups are kept.
• A version whose automatic install failed is not retried automatically; you can install it manually from the screen.

Automatic installs work on server installations and on Railway installations with RAILWAY_API_TOKEN set. On Docker Compose you update yourself (see container images).

#Critical updates

Releases with security or stability fixes can be marked critical. When a critical release is out:

• A red Critical update: bipanel … banner appears at the top of every Server Admin page, the release carries a Critical badge and its update button turns red.
• A panel notification is sent even when the mode is Off.
• Installation still follows your mode and maintenance window; the critical flag does not force an automatic install. If you are on Notify only, install critical releases manually as soon as you can.

#How an update is applied and verified

#Signature verification

• bipanel Hub signs every release manifest (version, channel, package digest, download address) with Ed25519. bipanel ships with the hub's public key and only accepts manifests that verify against it; a manifest with a bad signature is ignored.
• The downloaded package's size, its SHA-256 digest and the Ed25519 signature over that digest are each checked. If any of them fails, the update stops and the installed version stays as it is.
• The hub address cannot be changed from the panel; only the BIPANEL_HUB_URL variable set at install time decides it. Even with a different address, an unsigned package or one signed with another key is never installed.
• Pro installations download their package with their license, through a short-lived link, marked for that license. If the running Pro package is modified by hand, the panel raises a Panel package changed notification and Pro updates are paused.

#Steps on a server installation

Update to … (or an automatic install) goes through these steps, and the screen shows the state of each one along with the task log:

1. The package is downloaded and verified.
2. If the setting is on, the panel database is backed up (/var/lib/bipanel/backups/panel-db/).
3. The install script starts as a systemd unit independent of the panel service: it unpacks the package (Extracting package), installs dependencies (Installing dependencies), keeps the old installation as /opt/bipanel.prev and puts the new one in place (Switching to the new version), then restarts the service (Restarting the panel).
4. Health check: the panel must answer with the new version number within 90 seconds.

Sites, email and databases keep running without interruption; only the panel restarts for 1–2 minutes; reload the page afterwards. Dependencies are installed on the server with npm, so the server needs access to the npm package registry.

#Rollback

If the new version fails the health check, the previous installation is put back, the panel database is restored from the pre-update backup and the old version is started again. The broken installation is kept as /opt/bipanel.failed for inspection, the history shows Rolled back, and the administrator gets a notification. An update that has not finished after 30 minutes is marked as failed, and the installed version is unchanged.

#Updating from the command line with update.sh

/opt/bipanel/deploy/native/update.sh updates a server installation by hand, for when the panel does not start or cannot update itself. It runs as root, keeps the panel database (/var/lib/bipanel) and /etc/bipanel/bipanel.env, restarts only the panel service and waits up to 60 seconds for the panel to respond.

On servers set up with the installer, /opt/bipanel is not a git repository, so unpack a release package and pass it with --source. Get the package from the download page and compare its SHA-256 with the value shown there:

$ sha256sum bipanel-X.Y.Z.tar.gz
$ mkdir -p /root/bipanel-new && tar -xzf bipanel-X.Y.Z.tar.gz -C /root/bipanel-new
$ sudo bash /opt/bipanel/deploy/native/update.sh --source /root/bipanel-new/bipanel

Unlike updating from the panel, update.sh does not verify signatures or roll back on its own. It also switches the installation to whichever edition the package is: the package on the download page is the Community package, so update Pro installations from the panel.

#Container image updates

On Docker and Railway the file system comes from the image, so the panel does not download packages; a new version arrives as a new image. The Updates screen still checks the signed release manifest and shows the new version. Your data stays on the /data volume.

• Railway with RAILWAY_API_TOKEN set: Update switches the service to the new version's image and starts a redeploy; if no image was published for the release, the latest commit of the linked repository is deployed. Automatic update modes work here too. The panel and sites restart briefly during the deploy.
• Railway without a token: in the Railway dashboard, select the service and choose Redeploy, or switch the service to the new version's image.
• Docker Compose with a published image: set the image tag in docker-compose.yml to the new version, then pull the new image and recreate the container:

$ docker compose pull
$ docker compose up -d

• Docker Compose built from the release package (the route on the download page): unpack the new release package in the directory where you unpacked the first one (it overwrites the existing bipanel folder) and rebuild the image. Your .env file and the /data volume are kept:

$ curl -fsSL https://bipanel.io/api/v1/releases/X.Y.Z/download | tar xz
$ cd bipanel && docker compose up -d --build

In a container, operating system packages are updated along with the image. See Docker and Railway for setup details and safe updates and configuration for the security side of updates.