Skip to content

Update Prism

An installer or release-archive install updates itself from the public release channel https://releases.prism.tm/prism. Nothing has to be configured for the source: official builds carry the channel. A Debian package install is updated with a newer package instead (see Debian package).

Installing updates from Prism itself is off by default. Turn it on once:

  1. In the console open Configuration → Maintenance, switch on Allow installing updates from the console and save.
  2. Click Restart now next to the setting.

Restart and stop from the console need no setting: Prism offers them by itself when the service that runs it starts it again after a console restart (exit code 75) and leaves it stopped after a stop (exit code 0). The units from the installer and the Debian package do; see Run as a service. If Prism was started by hand, the console says that restart is unavailable.

Open Versions. The page shows the running version, the latest release of the channel and its release notes.

  • Update now and Stop and update install the latest release.
  • Reinstall installs the running version again.
  • A release tag such as v0.29.0 in the version field installs exactly that release, also an older one or a pre-release. Use it to go back to an earlier version.
  • Offline installation: choose the platform archive, SHA256SUMS and SHA256SUMS.sig downloaded on another machine. Verification is the same and needs no network.

When an install is not possible (updates not enabled, no write access to the directory of the executable, an update still on probation, no release source), the buttons are disabled and the reason is shown under them.

prism update asks the running Prism to do the same as the console:

Terminal window
cd ~/.prism
prism update check # exit 10: a newer release exists; 0: up to date
prism update install --yes # latest release of the channel
prism update install --version v0.29.0 --yes
prism update status # versions and the last update
Option Effect
--config PATH config used to find the running Prism (default config.toml in the current directory)
--url http://127.0.0.1:18000 address of the running Prism instead of the config; plain http:// only to a loopback address
--json one JSON object with exit_code
--timeout 10m how long install follows the job

The owner token comes from PRISM_ADMIN_TOKEN, else [console] admin_token_file, else <storage.dir>/console-token. Exit codes: 0 success, 10 newer release available (check), 1 failure or rollback, 2 usage error.

Check a downloaded release without installing it:

Terminal window
prism update verify --archive prism_v0.30.0_linux_amd64.tar.gz --sums SHA256SUMS --signature SHA256SUMS.sig
  1. Prism downloads the release’s SHA256SUMS and SHA256SUMS.sig and checks the signature with the release keys built into the running binary. An unsigned release, an unknown key or an archive whose checksum differs is refused and nothing changes.
  2. It unpacks the new binary next to the executable, checks that it reports the expected version and accepts the current config (prism config check).
  3. The fleet receiver, when Prism found it running as the same user (under a systemd user unit or as a plain process, which is restarted with its own command line), is replaced and checked first. Then companion programs (for example prism-service-agent) found next to prism, in ~/.local/bin or in ~/.local/libexec whose version differs are replaced; a program that is not installed is never added. Each replaced file is kept as <path>.prev.
  4. Prism stops accepting new connections, gives running requests, streams included, up to 60 seconds, copies the state directory to <storage.dir>/update/snapshots/ and starts the new binary in its place.
  5. The new version runs 15 seconds on probation. When its /health answers, it replaces the installed executable and keeps the previous one in <storage.dir>/update/backups/.

If the new version does not start, crashes or fails its health check during probation, it exits; the supervisor starts the old executable, which restores the state snapshot and the replaced companion programs and records the reason. The new version’s files are moved to <storage.dir>/update/rolled-back/. The Versions page, prism update status and <storage.dir>/update/journal.jsonl show every step and the reason.

If Prism was updated some other way, the Versions page marks the older components «out of date». Update to on a row, or Bring all in sync, replaces them from the signed release of the version Prism runs; Prism keeps running. With [console] allow_update on, Prism does this by itself about two minutes after it starts.

An install needs write access to the directory of the executable and free space for one copy of the state directory; otherwise the console says so and installs nothing.

[console] update_channel selects which release is “latest”:

Value Latest is
stable (default) the newest release without a - suffix
prerelease the newest release, -rc and -beta tags included

Set it on Versions or in Configuration → Maintenance → Release channel. A pinned version is installed regardless of the channel.

The console and prism update show new releases on a packaged Prism but do not install them. Download the new package and install it:

Terminal window
curl -fsSLO https://releases.prism.tm/prism/v0.30.0/prism_0.30.0_amd64.deb
sudo apt install ./prism_0.30.0_amd64.deb

Before the upgrade restarts the service, the new version runs prism config check /etc/prism/config.toml as user prism with /etc/prism/prism.env loaded. If the check fails, the running Prism is not restarted and keeps serving, the reason is in journalctl -t prism-deb, and apt reports the package as not configured. Fix the config and run sudo dpkg --configure -a.

Windows installs by hand: download the .zip, stop Prism, replace prism.exe, start it again.