Upgrading

One click in the admin, or `composer update`. A self-updating release goes live by switching a pointer, and goes back the same way if it fails its own checks.

3 min readView as Markdown

On this page

A site set up from the zip updates itself: open Modules, then Updates, and click Update. It needs no special server: PHP that can write to its own folder is enough, and each step is a request short enough for any shared host.

A site managed with Composer updates with Composer:

Terminal

composer update
php cms sync
php cms build

Your site's files (config/, content/, plugins/, public/media/, storage/, .env) are separate from Lettern's code, so an update of Lettern never touches them.

#What happens in the admin

Each release lives in its own folder, runtime/<version>/, and the one-line file runtime/current names the one in use.

Download and verify. The zip comes from the signed update list. Its hash and its signature must match, field by field. A failure here stops everything, with nothing changed.
Unpack and check. The release is unpacked beside the live one, and every file is compared with the release's own list.
Switch. One rename of runtime/current. Requests in flight finish on the old code. Dynamic pages answer 503 with Retry-After for the few seconds migrations take; static pages keep serving.
Migrate and check itself. The new code migrates the database and every package, lifts the gate, then checks the database, every module, the admin and the home page.
Settle, or go back. Any failure renames the pointer back, and the site runs the old code as before. For 15 minutes after that, three fatal errors in the new release's own code do the same. A plugin's fatal, or a memory limit, doesn't count.

Go back on the Updates screen returns to the previous release for as long as it is on disk (7 days). The database stays as it is: within a major, migrations only add.

#Security updates

Security releases install by themselves by default, on any signed-in admin's visit, or from cron with php cms packages:update --security-only. A public request never starts or advances an update. A quiet site with neither stays where it is, so add the cron line if nobody signs in for weeks.

They don't go by themselves when a plugin wouldn't suit the new version, when the release needs something the host lacks, while postponed (up to 14 days), or after failing twice. Each of those becomes a banner for people who can act on it. Turn them off under Updates, or with CMS_UPDATE_AUTO=false.

Checking sends nothing but a User-Agent with the version, at most every 12 hours. CMS_UPDATE_CHECK=false turns it off.

#When the host can't do it

If runtime/ isn't writable, or the host lacks ZipArchive or curl, Updates says so. Download the zip, upload runtime/<version>/ by FTP, and click Switch, or edit runtime/current by FTP and run php cms sync.

#Sites managed with Composer

A site without runtime/, a folder with .git and CMS_ALLOW_FILE_MODS=false all count as deployed: the screen only tells you a version is out, and you update through your deploy. Run php cms sync after the code changes, then php cms build.

#What changed

The changelog lists every release. Each package also has its own CHANGELOG.md, in English.

#Plugins

Every plugin is versioned on its own. On a site that updates itself, those from the store update from Updates, only from the store they came from, each with a backup and a Go Back for 7 days. Security versions go by themselves when they ask for no new capabilities. A store's advisory about what you run is a warning: Lettern never switches a plugin off for it.

A plugin whose requirements are not met (another plugin, a Lettern version, a PHP library) is switched off with the reason shown in Modules, instead of breaking the site.