Updating NetEnds

How updates reach you

When a release is published, NetEnds emails you its release notes, the oldest release it updates from when that matters, private download links for its files, the SHA-256 checksum of each file and the fingerprint of the release key. The release is signed with the same key as your first install, so the netends-release.pub you already hold verifies it; check its fingerprint against the email. The notes also ship inside the release, so a host with no network still has them.

There are two ways to apply a release, and both keep your .env, your secrets and your data:

• The updater — netends-update-offline.sh, installed on the host with the platform. It verifies the release, applies it, proves the platform came back healthy, and rolls back on its own if it did not. This is the route for routine updates.
• The installer — run the new release’s installer, the one-paste installer or install_offline.sh, as you did for the first install. It upgrades in place, but it does not roll back; Installing NetEnds lists exactly what it changes.

Apply an update with the updater

1. Put the new release’s platform file on the host, with the release public key saved as netends-release.pub in the same directory. Check the file against the checksum in the email first — see Verifying your download.

2. Run the updater:

   sudo /opt/netends/updater/netends-update-offline.sh \
        --bundle /path/to/netends-airgap-core-<version>.tar \
        --pubkey /path/to/netends-release.pub

The updater verifies the release’s checksums and signature, loads the new images, switches the install to the new release, and then runs the health gate below. The --pubkey option can be left out when netends-release.pub sits in the same directory as the file. It makes no network request.

Routine updates need only the platform file. On an install with Gia, when a release changes what the platform expects of Gia’s model server, the updater refuses to apply the platform file alone and says so: unpack the new Gia package in the same directory as the platform file and run the updater again, and it applies both together. Nothing changes on a refusal.

Before it changes anything, the updater also:

• Refuses an architecture mismatch — an x86_64 release on an arm64 host, or the reverse. The --skip-arch-check option overrides it.
• Refuses a downgrade to a release older than the one installed. The --allow-downgrade option overrides it.
• Refuses when free disk space cannot hold the unpack and the image load. The --skip-space-check option overrides it.
• Treats a release that matches the installed version as nothing to do. The --force option applies it again, which is useful to repair a half-applied stack.

Apply releases in version order, one at a time, and let each pass its health gate before the next. Where it matters, the release notes name the oldest release each one updates from; do not skip a release they mark as a required step.

The health gate

After the new release is running, the updater proves the update worked rather than assuming it. It checks every 10 seconds, for up to 10 minutes, until both of these hold:

1. The liveness endpoint answers — the stack is serving.
2. The device inventory API answers with an authentication challenge, not a server error. That proves the application started fully: the database and its migrations are up and the request pipeline is answering. No credential is needed on the host for this check.

An install whose license has expired still passes the gate: the application is fully up and only licensing is paused. That is deliberate — an expired license must not make every update roll back. Both checks must hold before the new version is recorded as installed.

Rollback

If the images fail to load or start, or the health gate never passes, the updater restores the previous release and brings the stack back up. The previous release’s images are still on the host — nothing removes them during an update — so this is a true rollback to the exact prior images, with no network needed. The previous web-server configuration is restored too.

After a rollback the status shows rolled_back with the reason. Read the updater’s output and docker compose logs in /opt/netends before you try again.

If even the previous release does not pass the health gate after the restore, the status shows rollback_unhealthy. Treat that as an incident: the platform is likely down and needs hands-on attention in /opt/netends.

HTTPS after an update

The updater brings each release’s HTTPS configuration with it under the installer’s rules: a certificate is made sure of first — generated when /opt/netends/certs/ holds none, never replaced when one is there — and an nginx.release.conf you edited is kept, with the new version parked beside it as nginx.release.conf.dist.

If your install still opens on plain HTTP after an update, its updater predates HTTPS by default. Run the new release’s installer once: it moves the install to HTTPS under the same rules and brings the updater on the host up to date, so later updates carry the change themselves.

Watching update status in the product

Each update writes its outcome and an append-only history that the product reads back. The Updates card on the Diagnostics & Support page (Diagnostics in the sidebar) shows the current version, when the updater last ran, the last result and a short recent history. Until the first update runs on a host, the card has no status to show and says the host updater is not installed. Gia can read the same status, so you can ask it whether the last update applied or rolled back.

Status values you may see

On the Updates card these appear with the underscores shown as spaces.

Status	Meaning
applied	The update installed and passed the health gate.
rolled_back	The update failed its gate; the previous release was restored and is healthy.
rollback_unhealthy	Even the previous release did not come back — an incident.
bundle_invalid	The release failed verification or the architecture check, or a downgrade was refused. Nothing on the host changed.

Confirming an update

After an update lands, confirm real data still flows: sign in, open the Devices page, and check the Diagnostics & Support page — the current version should read the new release, and the last result should be applied.

On the host, the installed release is written to /opt/netends/VERSION only after a passed health gate, the latest outcome is in /var/lib/netends/updater/status.json, and the history is in /var/lib/netends/updater/history.jsonl.