Hosting Gateway

Appearance

Rollback ​

If a gateway deploy goes bad, the recovery is to roll back the entire hivecast release. The gateway is not independently versioned from the rest of host-service today.

Today: hivecast-release-level rollback ​

A hivecast install lives at:

/home/ubuntu/hivecast/releases/hivecast-<version>-<commit>/

To roll back, stop the current Host, install the previous release, and restart:

bash
# Stop current
sudo systemctl stop hivecast-host.service hivecast-nats.service

# Symlink current → previous release
sudo ln -sfn /home/ubuntu/hivecast/releases/hivecast-0.1.23-prev-commit \
             /home/ubuntu/hivecast/current

# Restart
sudo systemctl start hivecast-nats.service hivecast-host.service

(The exact rollback procedure depends on how the production deploy is wired. The cloud deploy.sh keeps multiple release directories around so this kind of point-and-restart rollback works.)

What rolls back together ​

Rolling back a hivecast release rolls back everything:

  • The gateway code.
  • Every bundled package's code (chat, director, etc.).
  • The mx-cli bundled into the wrapper.
  • The host-service code.
  • The NATS server binary (which doesn't typically change between releases).

You cannot independently roll back just the gateway without also rolling back everything else.

What does NOT roll back ​

  • Persistent state on disk: <host-home>/runtimes/, credentials, etc.
  • The artifact registry (separate Gitea instance).
  • User-installed packages (under <host-home>/packages/global/) — those came from mx install and persist independently.
  • Packages currently running through matrix up from non-bundled installations.

Rollback safety check ​

Before rolling back, confirm the previous release is functional:

bash
ls -la /home/ubuntu/hivecast/releases/

You want to see the previous release directory present. If it's been cleaned up, you can't roll back without re-fetching.

After rollback:

bash
curl -fsS http://127.0.0.1:3198/healthz | jq .

The releaseVersion and releaseCommit should now reflect the rolled-back version.

Per-runtime rollback (target state) ​

A finer-grained rollback would let operators restart only the gateway runtime against an older host-service version, leaving other packages running. This requires:

  1. Per-runtime version pinning in <host-home>/runtimes/<id>/runtime.json.
  2. host-service the ability to load a runtime from a specific package version (not just the bundled one).

Both are target state. Today, per-runtime restart is supported (matrix stop <id> + matrix start <id>), but the runtime always loads from the currently-symlinked release.

Avoiding rollback ​

Rollback should be rare. The pre-merge gate (scripts/ci/premerge-local.sh) exercises the build, the test suite, and a smoke test against a fresh install. Catching regressions before they reach a release is much cheaper than rolling back.

The launch-readiness work (WORKSTREAMS/launch-readiness-atomic-writes-and-bootstrap/) also reduced the bootstrap-failure surface — corrupt runtime.json files no longer crash-loop the supervisor; hivecast start self-heals them.

See also ​

Source: Cloud deploy procedure in projects/deploy-cloud/deploy.sh. Rollback is operator-driven, not automated.