Skip to content
How to install

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.

Settings → Updates with a new version available

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.

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.

  1. Open Settings → Updates and read the release notes.
  2. Choose Update to followed by the new version.
  3. 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.

Terminal window
sudo /opt/wpl7/provision/update.sh --to=<version> --dry-run
Terminal window
sudo /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.

  1. An install too old for the release is told to update to an intermediate one first.
  2. 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.
  3. The panel stops, and its database is copied. Then the new version starts.
  4. The health gate waits for the new panel to report healthy, as the new version.
  5. 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 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.

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.

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 .htaccess move to .user.ini. See Change a PHP setting.
  • The database restarts once. wpl7-mariadb gets 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.

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.

  • 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.