How updates work
A self-hosted site can be told in its admin panel when a newer version of Choir Master CMS exists, and on most set-ups it can install that version with one click. This page explains how that works and which settings control it. It is for whoever runs the server. The admin's side of it is in Update your site with one click.
When the site checks
The site never checks on a timer. It checks only when an Admin or Site Admin opens the admin dashboard or the Updates page, and then only if the last answer is more than twelve hours old. The Check now button on the Updates page asks straight away.
- The answer is kept in the site's database, so it is asked for at most twice a day.
- A check gives up after eight seconds. A failed check leaves the last known answer in place and shows "The last check for updates did not work", with the reason. See When an update fails.
- Without a
LICENSE_KEYthe site never contacts the release server. See Your licence key for exactly what a check sends. - Managers cannot see the Updates page, and a Manager opening the dashboard does not trigger a check.
The three update modes
UPDATE_MODE decides what the site does when it learns of a new version.
| Value | What the admin sees | What it is for |
|---|---|---|
self | An Update now button. The site downloads the release, checks it, installs it and restarts itself. | A single server process with a disk that persists. |
notify | The version, the release notes and the steps to install it by hand. | Cloudflare Workers, several copies of the site, or anyone who prefers to control updates. |
off | "Updates for this site are looked after by whoever hosts it." No checks are made. | A site whose operator updates it some other way. |
A value that is not one of these is ignored, with the warning UPDATE_MODE is "...": use self, notify or off. Using notify (or Using self when the launcher started the site).
The default on each platform
If UPDATE_MODE is not set, the site picks the mode by how it was started. One-click updating needs the launcher, a small program (server/launcher.js) that starts the server and can restart it into a new version, or back into the old one.
| How the site runs | Default mode | Can UPDATE_MODE=self work? |
|---|---|---|
Node, started with npm start (which runs node server/launcher.js) | self | Yes. |
| The Docker image (its command is the launcher) | self | Yes. |
Node, started with npm run start:direct (node server/entry/node.js) | notify | No. The log says: UPDATE_MODE=self needs the server to be started by the launcher (npm start, or the Docker image); the admin panel will show update steps instead. |
| Cloudflare Workers | notify | No. The log says: UPDATE_MODE=self is not possible on Cloudflare Workers; the admin panel will show update steps instead. |
UPDATE_MODE=notify and UPDATE_MODE=off are always honoured. On a Cloudflare Worker the template wrangler.toml.example carries a commented-out UPDATE_MODE = "off" for a site that should not check at all.
npm run config:check is not started by the launcher, so it reports "mode": "notify" even on a site that will run in self mode. The Updates page on the running site is the reliable place to see the mode.
On Cloudflare, your wrangler.toml is yours
A release never contains or changes your wrangler.toml. When a release needs something new in it, the release notes on the Updates page say so and wrangler.toml.example in the download shows it. Version 1.6.12 is the first to: two lines in [assets], which a site keeps working without. See Changes a release needs in wrangler.toml.
Other settings
| Variable | Default | What it does |
|---|---|---|
LICENSE_KEY | none | Your licence key. Without it no check is made. |
UPDATE_MODE | by platform, as above | self, notify or off. |
UPDATE_CHANNEL | not set | stable, beta or dev. See Beta versions and update channels. |
UPDATE_URL | https://updates.choirmastercms.com | The release server's address, with any trailing slash removed. Change it only to point at a release server of your own for testing. |
DATA_DIR | ./data | Where downloaded releases (releases/) and the copies of the SQLite database made before each update (backups/) are kept. It must be writable and must survive restarts. |
DATA_DIR is relative to the folder the server is started from, so give it a full path (/srv/choirmaster/data) unless you always start from the same place.
PORT and DATA_DIR must be real environment variables of the process that starts the launcher. The launcher reads them before the server starts, so it does not see values that arrive only through a secrets manager or a NAME_FILE setting. If PORT is wrong the launcher watches the wrong port for the health check and an update is wrongly rolled back.
Where updated code lives
After a one-click update the site runs from DATA_DIR/releases/<version>/, not from the code it was installed with.
data/
choir.sqlite the database (with SQLite)
storage/ uploaded files (with local storage)
backups/ copies of the SQLite database made before each update
releases/
state.json which release is in use
1.6.12/ the downloaded release
state.json records current (the downloaded release in use, or null for the installed code), previous, pending (a release waiting for its first start) and lastResult (how the last attempt went). The launcher keeps the release in use and the one before it and deletes older downloads.
The newer version always wins. A downloaded release is used only while its version is higher than the installed code's. If you later install a newer version by any other means (a new image, a new folder, a deployment script), the installed code takes over and the downloaded release is ignored. The reverse matters too: if you install an older version by hand while DATA_DIR/releases holds a newer download, the download keeps running. To make the installed code run, delete DATA_DIR/releases and restart.
The launcher itself is never replaced by an update. It always comes from the installed code, and it is kept small on purpose. Commands you run by hand (npm run db:migrate, npm run config:check) also use the installed code, not the downloaded release.
When not to use one-click updates
Set UPDATE_MODE=notify (and update the way you deploy) if any of these is true:
- You run several copies of the site behind a load balancer. Each copy would download and restart on its own.
- An orchestrator such as Kubernetes replaces containers from an image. A downloaded release lives in the container's disk and is lost when the container is replaced.
- The host's disk is throw-away, so
DATA_DIRdoes not survive a restart.
What does not exist
- There is no unattended update. Nothing installs a release unless an admin presses Update now.
- There is no downgrade button. Going back is automatic only when a new version fails to start (see When an update fails). To go back by hand, see Update by hand.