Updating WPL7
The panel checks for a new version once an hour, and the header says when there is one. An update replaces the panel, checks that the new one is healthy, and puts everything back if it is not. Site containers keep running throughout.

Channels
Section titled “Channels”Each install follows one channel, and the panel offers only that channel’s versions.
| Channel | Follows | For |
|---|---|---|
stable |
Published releases | Servers with customers on them |
edge |
The rolling build of main, published after every merge |
Trying what comes next, on a server you can afford to break |
The installer follows stable unless given --channel=edge, and update.sh --to=edge moves an
install to edge.
Check for a new version
Section titled “Check for a new version”The hourly check runs at a minute picked for your install, and downloads nothing. Right after an update, the new panel asks once without waiting for that minute. Check now on Settings → Updates asks at once. With an alert address set in Settings → Monitoring, it also emails you once per new version.
“Could not check for updates” means GitHub refused or did not answer, often because of its limit
on anonymous requests. A read-only WPL7_GITHUB_TOKEN in deploy/.env lifts that limit.
Apply an update from the panel
Section titled “Apply an update from the panel”- Open Settings → Updates and read the release notes.
- Choose Update to followed by the new version.
- Confirm with Update now.
The update refuses to start while any job is queued or running. While it runs, every page shows a banner and the panel refuses changes. The page shows each step, goes quiet for a minute or two while the panel is replaced, then offers Reload.
Apply an update on the server
Section titled “Apply an update on the server”sudo /opt/wpl7/provision/update.sh --to=<version> --dry-runsudo /opt/wpl7/provision/update.sh --to=<version>--dry-run changes nothing. Use --to=edge on the edge channel. The button in the panel runs the
same script.
What happens
Section titled “What happens”- An install too old for the release is told to update to an intermediate one first.
- The new images are pulled. If the nightly housekeeping is removing old Docker images at that
moment, the update waits for it first, for ten minutes at most. Past that it stops, and you can
run it again. The pre-flight warns about keys missing from
deploy/.env, little free disk, or a release that needs downtime. - The panel stops, and its database is copied. Then the new version starts.
- The health gate waits for the new panel to report healthy, as the new version.
- On any failure, the rollback restores the previous images, files and database copy.
There are no down-migrations. A failed update goes back to the whole previous state. The log of
the last update is /srv/panel/update/current.log. The database copy of the last update stays
beside it, and a healthy update removes the copies of earlier ones.
Image mode and checkout mode
Section titled “Image mode and checkout mode”| Image mode | Checkout mode | |
|---|---|---|
WPL7_SOURCE |
image, the default |
build |
| The panel comes from | The released image | The server’s own checkout, compiled there |
| Update with | Settings → Updates, or update.sh |
provision/deploy.sh |
| Rolls back to | The previous image and files | The previous commit |
The button in the panel works in image mode only.
update.sh --force moves a checkout-mode install to image mode, replacing the panel built there.
In checkout mode the version reads like 0.4.1-source: the panel was built from a checkout that
has 0.4.1 in it. Only a newer release counts as an update. Settings → Updates shows the commit
beside the version.
What the panel does afterwards
Section titled “What the panel does afterwards”Once up, the new panel runs the Finish panel update job. It runs the steps each skipped release needs, updates every worker server, and lifts the read-only state. Settings → Updates shows how the post-update tasks went.
A failed step is a failed job, never a rollback, because the new version is already running. Fix what it reports, then choose Re-run.
Since 0.3.2 The panel then rebuilds every site container that runs an older site image than its server now has. Each rebuild is a job of its own, with its own rollback. Sites on a worker server follow within the hour after that server updates. A site busy with another job is rebuilt at the next hourly check.
Since 0.4.1 A new PHP patch release does not wait for an update. Each server gets a new site image with it, and its sites move the same way, as PHP updates explains.
In checkout mode, the same happens when a rebuild changes the site images. deploy.sh and
build.sh --images pull the newest WordPress base image for each rebuild.
The move to PHP-FPM
Section titled “The move to PHP-FPM”Since 0.3.3 This update moves every site from Apache with mod_php to nginx, Apache and PHP-FPM, as How WPL7 works shows. You start nothing. Each site moves when the panel rebuilds it on the new site image, as above.
- The page cache turns on for every site. Every site follows the default unless it says otherwise, and the default is on. To keep it off everywhere, switch off Page cache in Settings → Sites. A site can still choose On for itself.
- Each site is recreated once. It does not answer for a few seconds. Sites on a worker server move within the hour after that server updates.
- PHP settings in
.htaccessmove to.user.ini. See Change a PHP setting. - The database restarts once.
wpl7-mariadbgets its new buffer pool, so every site on that server is without its database for a few seconds. - Traefik restarts once. It takes on HTTP/3’s port. Sites can answer 504 until the panel has attached it to their networks again, within a minute.
A WooCommerce store on plain Geolocate stays Off, and its Caching card says why.
If a site cannot move
Section titled “If a site cannot move”The job checks the site before and after the move. A site that answered before, and does not answer
on the new setup, gets its old container back. Its .htaccess lines go back too. The
Recreate site container job fails, and the site’s Overview tab says
This site still runs the old PHP setup, with the reason and Retry.
The site then works as it did, without either cache. It stays on its old image through anything else that recreates its container, while Docker still has that image. A rebuild of the site images can delete it, and then the site tries the move again instead. It also tries again when its server has a newer image, or when you choose Retry or Recreate container.
A site that did not answer before the move stays on the new setup, and the job warns. A stopped site moves and stays stopped, without a check.
Limits
Section titled “Limits”- A panel that always has a job running keeps updates waiting.
- The button needs the panel’s SSH access as root to its own host. A host that refuses root logins updates from the command line.
- An update that brings new site images rebuilds every site once. Each site is unreachable for a second or two.
- A site that cannot move to PHP-FPM keeps its old image’s PHP, and the PHP security releases in newer images do not reach it until it moves.
- The move cannot tell what a site’s visitors should see. A page that changes by something the request does not show needs a rule or Off, as Caching says.