# Upgrades

> Upgrade a Weald relay by digest rather than by tag: verify the signature, roll forward, roll back, and keep clients from meeting a protocol they cannot speak.

Source: https://getweald.com/docs/self-hosting/upgrades
Last modified: 2026-08-03

---

## Upgrade by digest

Last updated 2026-08-03

Upgrade a Weald relay by pinning an image digest, not a tag. Every release publishes its digest and its binary SHA-256, signed, and the client shows the digest its relay reports so a mismatch is visible to every connected member. Schema migrations stay forward-compatible for one minor version, so an upgrade is a rolling restart rather than an outage.

The relay is published: wealdrelay-v0.1.5, built reproducibly and pinned by digest. Pin ghcr.io/weald-protocol/wealdrelay@sha256:e78268855dd932bb06ce975bacda3fd8df6a4c28aa728838b356b3f61866c117.

## Why a digest

A tag is a name somebody can move. A digest is the content, so pinning one is the difference between running what you reviewed and running whatever that name points at today.

The published container digest is reproducible from the tagged source, so a third party can rebuild and compare.

## The sequence

- Read the release notes and the advisory, if the release carries one.
- Verify the signature on the published digest and the binary SHA-256.
- Pin the new digest in your compose file or unit file.
- Restart. Migrations run forward and an old process and a new one can share the database for the length of a deploy.
- Confirm the digest the client reports matches the one you pinned.

## Rolling back

Pin the previous digest and restart. Because migrations are forward-compatible across one minor version, a rollback within that window is the same operation in reverse.

Across a larger gap it is not, and the honest answer is to restore a backup taken before the upgrade rather than to migrate a database backwards.

## The release check

The relay fetches the public release feed once a day and reports the result on its readiness endpoint. A relay behind a security release shows up in the client as an update notice, naming the release and its advisory, to admins only.

It is an unauthenticated GET of a public file. There is no auto-upgrade, no telemetry alongside it, and WEALD_RELAY_RELEASE_CHECK=off turns it off for an air-gapped install.

## Two different signals

The client distinguishes them, and so should you.

*Digest states and what they mean*

| State | What it is | Response |
| --- | --- | --- |
| Digest does not match its source tag | An alarm. Something is running that no release describes | Investigate before anything else |
| Digest is older than the latest release | A chore | Schedule an upgrade |

Rendering the second as the first is how a security banner gets trained into background noise, which is why they are drawn differently.

## What a digest check is worth

It catches deployment drift and operator mistakes. It does not prove what a remote host is executing, because a modified binary can misreport its own digest.

What survives is this: a relay you run, from an image you verified, is running what you think it is. Verify is the procedure for checking the rest.