Updates

Every service is versioned on its own (vMAJOR.MINOR.PATCH) and released the same way. An instance keeps releases in its release store (/var/lib/xvii/releases, served at https://xvii.network/releases/), and xvii-node installs from there.

How updates work

When a service is updated, xvii-node:

checks the release's binary against its SHA256SUMS;
swaps the service's current link to the new version and restarts it (its database migrations run on start);
waits up to 30 seconds for /healthz to answer;
if it doesn't, puts the previous version back, restarts it, and reports the failure.

Units and settings that didn't change aren't touched, so an update restarts only the service being updated.

Update from home

home → Services shows each service's installed version and the newest one in the store. Press Update, confirm, and watch the state go from updating to running. If the new version doesn't become healthy, home shows the error and the service is back on its old version.

A service's sheet also lists every version in the store: install an older one the same way to roll back by hand.

Update from the shell

xvii-node status                  # installed and wanted versions, health
xvii-node install pages           # the newest version in the store
xvii-node install pages v2.3.1    # a given version (also to roll back)
xvii-node logs pages 100

Getting new releases into the store

Releases come to an instance's store in one of three ways:

Releases of xvii are published at https://xvii.network/releases/ (index.json lists every service's versions, newest first). On the control plane, fetch one into a folder and import it:

svc=pages v=v2.3.1 arch=$(dpkg --print-architecture)
d=$(mktemp -d) && cd "$d"
base=https://xvii.network/releases/$svc/$v
curl -fsSO "$base/manifest.json" && curl -fsSO "$base/SHA256SUMS"
curl -fsSO "$base/${svc}d-linux-$arch"
xvii-node import "$d" "$v"

import checks the checksums and refuses a release that doesn't match.

A release archive (a .tar.gz with manifest.json, SHA256SUMS and the binaries) can be uploaded to home by a superuser or a token with the deploy scope:

curl -fsS -X POST -H "Authorization: Bearer $XVII_TOKEN" \
  --data-binary @pages-v2.3.1.tar.gz \
  "https://xvii.network/api/v1/admin/releases?version=v2.3.1"

A version is uploaded once; uploading it again answers 409. This is what CI does when you build your own releases.

Every service repository builds its release with make (the panel, then Linux binaries for amd64 and arm64, then dist/manifest.json). make BRAND=acme DISPLAY="Acme Cloud" builds a white-label release, see Look and branding.

The store keeps each service's five newest versions, plus whichever is installed or wanted.

What to check after an update

home → Services: the service is running and healthy at the new version.
curl -fsS https://<service>.xvii.network/api/v1/health
The service's own panel opens and lists your data.
For apps and domains: nodes and name servers still report in (xvii apps nodes, domains → Accounts).

Read a release's notes before skipping several minor versions of a service that holds data. Migrations are applied in order on start; a downgrade below a version whose migrations ran is not supported, so back up before major updates and roll back by restoring, not by installing the old binary.

The node agent

Nodes update themselves: the control plane names the newest xvii-node in the store as part of their desired state; an agent on an older version downloads it, checks its checksum and restarts into it. Its workloads keep running; relayed traffic pauses for the restart. Keep agent updates away from critical jobs when you can.
The control plane's own agent is updated by hand: install the new binary over /usr/local/bin/xvii-node and systemctl restart xvii-node. Services keep running meanwhile.
Name servers and mail edges run the same binary; update them the same way.

The CLI

The CLI's builds live in the store under /releases/cli/. People update with xvii update; the CLI checks once a day and mentions a new version. To publish a new CLI to an instance, build it in the cli repository and upload it to /var/lib/xvii/releases/cli (make publish VERSION=vX.Y.Z does both).

Downtime

An update restarts one service. Its panel and API are unavailable for the few seconds it takes to start; sites on pages, apps on nodes, DNS on the name servers and the other services keep working. id's sign-ins pause while id restarts; existing sessions continue.