Skip to content
Docs menu

Update a self-hosted Venom Cloud

Check for a signed release, upgrade with a preflight, a database backup, a health check and automatic rollback, roll back from the console or by hand, switch on automatic updates in a maintenance window, use the preview channel, and upgrade an air-gapped server from an offline bundle.

View .md

A server installed with install-cloud.sh stays current with one command, venom-cloud upgrade, and goes back with another, venom-cloud rollback. Nothing contacts the internet unless you ask it to, and every release is checked against its signature first.

See what is new

Settings, Updates (/settings/updates, owners and admins) shows the version this server runs. Check now is the only time the app itself calls out (the servers call out only to upgrade, and in the window when you switch on automatic updates): it reads the latest release's SHA256SUMS and its minisign signature from the public releases repository, verifies the signature, and tells you whether a newer release exists and whether you can go straight to it. It sends no install id, no cookies and nothing else. An unsigned or badly signed release is never offered. Servers with no network never see anything: use an offline bundle.

The check needs the release signing key. The image ships it as release/minisign.pub (the same file the release writes into the installers); VENOM_RELEASE_PUBKEY in .env overrides it, and VENOM_RELEASE_PUBKEY_FILE points at a different key file.

Upgrade

venom-cloud upgrade

The upgrade runs on the server, not from the web page: the container replaces itself, and the app never gets the Docker socket. In order, it:

  1. Checks the server: Docker works, there are 2 GB free for the backup and the new image, the database answers, and the running version is at least the release's min_from when it names one (so no migration step is skipped).
  2. Pulls the new image by its digest while the old release keeps serving. If the pull fails, nothing has changed.
  3. Backs up the database to /opt/venom/backups/pre-upgrade-<time>.sql.gz.
  4. Switches the image and starts it. The app applies its migrations on start.
  5. Checks health through HTTPS.
  6. Rolls back by itself if that fails: it puts the previous image back and, only if that cannot run on the migrated database, restores the backup. The backup is always kept. The command exits non-zero and says what it did.

Flags: --version X.Y.Z for a specific release. venom-cloud status shows the version. /opt/venom/state/history.log lists every upgrade and rollback with its result.

Roll back

venom-cloud rollback

switches to the release you were on before the last upgrade (its image is recorded in state/previous.env) and checks health. Running it again goes forward. This is safe because database migrations are expand/contract: a release only removes what the one before it already stopped using, so the previous image runs on the newer schema. The one thing a rollback cannot do is undo data the new release wrote in a form the old one ignores.

venom-cloud rollback --restore --yes also replaces the database with the backup taken before that upgrade. Everything written since is lost; use it only when the previous release cannot run on the migrated schema.

Air-gapped: an offline bundle

On a connected machine with Docker, from a checkout (or with the release directory from make release):

scripts/release/cloud-bundle.sh --release dist/release/1.2.3 --out venom-cloud-bundle-1.2.3.tar

make cloud-bundle RELEASE=dist/release/1.2.3 OUT=venom-cloud-bundle-1.2.3.tar does the same.

Carry the tar to the server and run:

venom-cloud upgrade --bundle venom-cloud-bundle-1.2.3.tar

The bundle holds the release's signed SHA256SUMS and signature, the image digest file, the image (docker save) and a checksum of that tar. The server verifies the signature with the release key (a bundle it cannot verify is refused unless you check it another way and add --allow-unsigned), checks the digest file against the signed sums and the tar against its checksum, loads the image and runs the same upgrade with the same backup and rollback. It makes no network call. The tar's content is vouched for by the registry at build time and by that checksum; the signature covers the digest the image was pulled by.

From the console

The app never runs Docker, so the console does not upgrade anything itself. It writes what you ask for into the database, and each server picks that up with venom-cloud tick, a cron entry the installer writes that runs every five minutes (on a Mac, a LaunchAgent that runs it at login and every five minutes: Install Venom Cloud on a Mac). An install from before the tick existed gets it with its next venom-cloud upgrade. If no server has reported in the last 15 minutes, the page says so and the buttons are hidden.

On Settings, Updates:

  • Servers lists every app server with the version it runs, the release it would roll back to and when it last reported. An Auto Scaling group shows each of its servers.
  • Upgrade now queues an upgrade for every connected server, to the newest release on your channel or to the version you type. Each server runs the same steps as venom-cloud upgrade, including the backup, the health check and the automatic rollback.
  • Roll back on a server's row queues venom-cloud rollback for that server. It switches the image only. To also restore the pre-upgrade backup, run venom-cloud rollback --restore --yes on the server.
  • Requests shows what was asked from this page and whether it is queued, running, done or failed, with the server's message. You can cancel a request until a server picks it up.
  • History lists every upgrade, rollback and restore on every server, with the versions and the result. The servers write it as they go; it is the same record as state/history.log.

Automatic updates

Automatic updates are off until an owner or admin switches them on in Settings, Updates. You choose:

  • The window: a day of the week (or every day) and an hour, in a time zone you pick.
  • What to take: patch releases only (1.4.2 to 1.4.3), or minor releases too (1.4.2 to 1.5.0). A major release is never installed automatically.
  • The channel: stable, or preview (below).

In the window, each server checks the channel once. It takes the newest release its setting allows. With patch only, when the newest release is a later minor version, the server looks for the newest patch of its own minor version instead. Then it upgrades with the same preflight, backup, health check and rollback as a manual upgrade, and the result shows in the history. Outside the window, and while automatic updates are off, no server contacts the releases repository.

The installer's --auto-update yes switches automatic updates on for a new install the first time its tick runs. After that, the console is the one place to change them. The old weekly cron entry is gone.

Channels

Stable is the latest release. Preview also offers pre-releases (versions such as 1.5.0-rc.1) before they reach stable. The releases repository keeps a small CHANNELS file that names the newest version on each channel. That file only points at a release: the release it names is checked against its signed SHA256SUMS like any other, and a pre-release that does not verify is never offered. Check now uses the channel you picked in the automatic-update settings. install-cloud.sh --channel preview installs from the preview channel.

The release manifest

Each release can carry venom-cloud-X.Y.Z.json, listed in the signed SHA256SUMS. It names min_from, the oldest version the release upgrades from. A release that contracts the schema (removes what the release before it stopped using) names that release, so the preflight refuses a jump past it and tells you which version to go through first.