Updating and rolling back

Simplified Chinese

pwikit installed as a system service looks for new releases on GitHub and installs them by itself during an update window. When an update fails, the previous release is put back automatically. You can also update by hand at any time, or go back to the previous release.

This page covers when automatic updates happen, what happens when one fails, how to update and roll back by hand, and the settings involved. Installing the service is covered in Deployment.

Checking the current version

pwikit version

Prints the release, the commit it was built from, the platform and the bundled PostgreSQL version. See Command line.

Automatic updates

How an update happens

pwikit service install also registers a task that checks for and installs new releases, and pwikit service uninstall removes it. While the service is stopped, the task does nothing.

An automatic update goes through these stages:

1. Check. Every hour pwikit fetches the details of the newest release from GitHub. A new release is announced in the admin panel at once, and everyone who can open the admin panel gets a notification.
2. Schedule. As soon as a release newer than the running one is found, the update is scheduled at a random time in the next update window (03:00–05:00 by default, in the zone set by time_zone, or the server's time zone when it is not set). From then on the admin panel shows when it will run, and for the 10 minutes before it every page of the sites shows an update banner.
3. Prepare. At the scheduled time pwikit downloads the release, checks its sha256, and has the new release check this instance's database. If any step fails, the update is abandoned and the site is not touched.
4. Install. pwikit stops the service, takes a rollback point where one is needed (see Rollback points), replaces the executable and starts the service. While the service is down, visitors see an "updating" page.
5. Confirm. pwikit waits for the new release to serve pages. If it does not within 15 minutes, the update is rolled back automatically (see When an update fails).

With min_age set, a release is scheduled only once it has been out that long. If the scheduled time is missed, for example while the machine is asleep, the update moves to the next window.

time_zone takes a name from the time zone database, such as Asia/Shanghai or Asia/Tokyo; a form like UTC+9 is not accepted. For a fixed offset write Etc/GMT-9. The sign is reversed, so it means UTC+9.

Releases that are not installed automatically

In these cases a new release is only announced in the admin panel:

Case	What to do
The release moves the bundled PostgreSQL to a new major version	Update by hand with pwikit update; see Bundled PostgreSQL major versions
The release failed before and was rolled back	Fix the cause, then retry with pwikit update
The release was skipped with Skip this release	Install it with pwikit update
Automatic updates are postponed	The next update window after the postponement schedules it again
min_age is set and the release has not been out that long	Once it has, the next update window schedules it
A release is held by pwikit update -to or pwikit update rollback	Release the hold with pwikit update unpin
Automatic updates are off	Update by hand with pwikit update
The running program is not a release (built without a release number)	Nothing is checked or installed
pwikit runs in a container	Pull the new image; see Running in a container

Except in a container or on a build without a release number, a superuser can also install these releases with Update now in the admin panel; see Update now.

The banner and the admin panel

Everyone who can open the admin panel sees notices at the top of it about new releases, scheduled updates, completed updates and rollbacks, and gets a notification when a scheduled check first finds a new release. Superusers can postpone, skip or start an update from these notices, and see why a failed update failed.

For the 10 minutes before an automatic update, the top of every page on every site of the instance shows every visitor an update banner. With public_banner = false, only the admin panel announces it.

Update now

Once a new release is found, a superuser can choose Update now in the admin panel notice. The update is scheduled 10 minutes later with the usual banner, and then runs like an automatic update.

Updating now ignores the update window, the age of the release, a skip, a postponement and a held release, works with automatic updates off, and installs a release that moves the bundled PostgreSQL to a new major version. Postponing cancels it before it starts. To start at once, use a manual update.

Postponing and skipping

From the admin panel or the command line:

pwikit update postpone
pwikit update skip

Action	Effect
Postpone	Cancels the scheduled update and installs nothing automatically for 24 hours. It is then scheduled in the next update window, usually one night later
Skip	Cancels the scheduled update and never installs that release automatically. Later releases update as usual

Turning automatic updates off

In pwikit.toml:

[update]
auto = false

pwikit still checks for releases every hour and announces them in the admin panel. check = false stops the checks altogether. Restart the service after changing either. Every setting is listed in Configuration.

Updating by hand

Installing the newest release

On Linux and macOS:

sudo pwikit update

On Windows, run pwikit update in a terminal opened with Run as administrator.

A manual update starts at once and shows no banner. Otherwise it goes through the same stages as an automatic one, and is rolled back the same way if it fails. It ignores the update window, the release age and skipped releases, and it also installs a release that moves the bundled PostgreSQL to a new major version.

Neither kind of update registers the system service again or changes its options. The executable the service points at is replaced in place, and the registration stays as it was.

pwikit update check only looks up the newest release and changes nothing.

Installing a given release

sudo pwikit update -to v1.0.1

When the release is older than the running one, pwikit holds it after installing, and automatic updates do not move past it. Release the hold with:

pwikit update unpin

Whether an older release can be installed depends on the database; see Older releases and the database.

An instance that does not run as a system service

Such an instance is not updated automatically. Stop pwikit serve, then run pwikit update. Once pwikit has replaced the executable and taken a rollback point, start pwikit serve again. pwikit update refuses to run while pwikit serve is running.

Rolling back

When an update fails

If the new release does not serve pages within 15 minutes, pwikit:

1. stops the new release and shows the "updating" page;
2. puts back the previous executable, and the data as the rollback point holds it;
3. starts the previous release and confirms it serves pages;
4. marks the release as failed, so it is not installed automatically again;
5. shows a rollback notice in the admin panel and, when a mail server is set up, mails every superuser with an email address the reason it failed.

Every step is written to logs/update.log in the data directory. The new release serves nobody until it is confirmed, so an automatic rollback loses no data.

If a step before the service is stopped and the new release put in place fails, for example the download or a lack of disk space, the previous release keeps running or is started again, the data is left as it was, and the scheduled update is kept and retried later.

Rolling back by hand

For 7 days after an update you can go back to the release before it:

sudo pwikit update rollback

When the rollback point holds the database, pwikit asks for confirmation first.

Note When the rollback point holds the database, rolling back loses everything written since the update, including new pages, edits, ratings and posts. Roll back only when the new release cannot be used.

-yes skips the question. After a rollback, automatic updates are held at the previous release until pwikit update unpin.

Rollback points

Every update takes a rollback point in update/rollback/ in the data directory and keeps it for 7 days:

What the update changes	Rollback point	Rolling back
No database changes, or only changes older releases can run on	The previous executable	Puts back the executable; the data stays as it is
Database changes older releases cannot run on, with the bundled PostgreSQL	The previous executable and a full copy of pgdata/	Puts back the executable and pgdata/
Database changes older releases cannot run on, with your own PostgreSQL	The previous executable and a backup of the database	Puts back the executable and restores the database
A new major version of the bundled PostgreSQL	The previous executable and the previous pgdata/	Puts back the executable and the previous pgdata/

Copying pgdata/ needs as much free disk space as the database takes. Without it the update is abandoned and the reason recorded.

Update status

pwikit update status shows the running release, the result of the last check, the scheduled update, the last update and the rollback point available. When nothing is scheduled, it says why. See Command line.

Bundled PostgreSQL major versions

One major version of PostgreSQL cannot read the data another one wrote. A pwikit release that moves the bundled PostgreSQL to a new major version is not installed automatically. When you run pwikit update by hand, pwikit:

1. backs up the database while the service is still running;
2. stops the service and moves the old pgdata/ into the rollback point;
3. puts the new release in place, whose PostgreSQL creates a new pgdata/ and restores the backup into it;
4. starts the service and confirms it.

If this fails, the old pgdata/ and executable are put back. How long it takes depends on the size of the database.

Older releases and the database

A new release may change the database structure. Each change says whether older releases can run on it:

• A compatible change: older releases keep running on the changed database. Going back to one needs no restore.

• A breaking change: older releases refuse to start on the changed database, with:

  pwikit: the database was upgraded by pwikit v1.1.0, which applied 0011_example.sql; this pwikit (v1.0.0) cannot run on that schema. Run pwikit v1.1.0 or a newer release, or restore a backup taken before the upgrade

  Run the release the message names, or restore a backup from before the upgrade. Within 7 days, pwikit update rollback does this too.

pwikit migrate status lists changes applied by a newer release as newer (compatible) or newer-breaking. See Command line.

Download source and mirrors

pwikit downloads releases from GitHub, which needs github.com and objects.githubusercontent.com. For a server that cannot reach GitHub, name a mirror. pwikit then fetches every file from the mirror first, and turns to GitHub when the mirror fails, serves a file that does not match its checksum, or sends nothing for a minute:

[update]
mirror = "https://wikit.unitreaty.org/projwikit/update"

A command writes it without editing the file by hand. Without an address it shows the current mirror, and an empty address clears it:

pwikit update mirror https://wikit.unitreaty.org/projwikit/update
pwikit update mirror
pwikit update mirror ""

Restart the service after changing it. An instance installed from a mirror has it written already.

A manual command takes one as well:

sudo pwikit update -mirror https://wikit.unitreaty.org/projwikit/update
pwikit update check -mirror https://wikit.unitreaty.org/projwikit/update

https://wikit.unitreaty.org/projwikit/update is a mirror run by the ProjectWikit maintainers. It passes on the release files from GitHub for servers, such as those in mainland China, that cannot reach GitHub reliably.

Note ProjectWikit releases are not signed. pwikit checks a file against the sha256 in the release manifest, and the manifest itself comes from the mirror. With a mirror configured, automatic updates install whatever program that mirror serves. Use only a mirror you trust.

Network access

Checking for releases contacts GitHub at regular intervals, or the mirror if one is set and GitHub only when the mirror fails, so they see the server's IP address. With check = false, pwikit contacts neither and announces no releases.

Running in a container

pwikit running in a container is not updated automatically and registers no task. Pull the new image and recreate the container:

docker compose pull
docker compose up -d

See Deployment.

Settings

The update settings are listed below; see also Configuration. Environment variables do not reach the system service or the task; for a service, use pwikit.toml, or options given after -- when installing it.

pwikit.toml [update]	Option	Environment variable	Default	Meaning
auto	-update-auto	PWIKIT_UPDATE_AUTO	true	Install new releases by themselves
public_banner	-update-public-banner	PWIKIT_UPDATE_PUBLIC_BANNER	true	Show the update banner to every visitor
check	-update-check	PWIKIT_UPDATE_CHECK	true	Look for new releases
window	-update-window	PWIKIT_UPDATE_WINDOW	03:00-05:00	Hours for installing releases, read in time_zone. May cross midnight, such as 23:00-01:00, and must span at least 11 minutes
time_zone	-update-time-zone	PWIKIT_UPDATE_TIME_ZONE	empty	The zone window is read in. Empty uses the server's time zone; a value overrides it. Use a name from the time zone database, such as Asia/Shanghai or Asia/Tokyo; a form like UTC+9 is not accepted. For a fixed offset write Etc/GMT-9: the sign is reversed, so it means UTC+9
min_age	-update-min-age	PWIKIT_UPDATE_MIN_AGE	0s	How long a release must have been out before it is installed automatically, such as 24h or 48h. With 0s, a release is scheduled in the next window as soon as it is found
mirror	-update-mirror	PWIKIT_UPDATE_MIRROR	empty	Mirror to use when GitHub cannot be reached

The options belong to pwikit serve. For a system service, give them after -- when installing it:

sudo ./pwikit service install -- -update-window 02:00-04:00