HiveCast Platform

Appearance

Operations: Deploy package update ​

For the conceptual model see Deployments / Rollouts. This page is the operator's playbook for the present-state manual deploy.

Today: per-Device wrapper upgrade ​

The wrapper bundles the package set. Upgrading "a package" today means upgrading the wrapper version on each Device.

bash
# On each target Device
sudo apt update
sudo apt install hivecast=0.1.<new>
hivecast stop
hivecast start

# Verify
hivecast --version
matrix invoke host.control status '{}'
matrix invoke system.runtimes runtimes.list '{}'

For a small fleet, do this in canary order:

  1. Upgrade one Device first (canary).
  2. Verify health on that Device.
  3. Wait observation window (10-30 minutes).
  4. Upgrade ~10% of fleet.
  5. Verify, wait.
  6. Upgrade rest.

Health verification per Device ​

After each upgrade:

bash
# 1. The supervisor is up
hivecast status

# 2. The runtimes started
matrix invoke host.control status '{}'

# 3. Bus actors respond
matrix invoke system.runtimes runtimes.list '{}'
matrix invoke system.devices devices.list '{}'

# 4. HTTP gateway responds
curl -fsS http://127.0.0.1:3100/healthz
curl -fsS http://127.0.0.1:3100/api/apps

# 5. App pages load
curl -fsS http://127.0.0.1:3100/apps/edge/ | head

If any check fails, do not proceed to the next Device. Investigate and resolve before continuing.

Rolling back during deploy ​

If health degrades after upgrade:

bash
sudo apt install hivecast=0.1.<previous>
hivecast stop
hivecast start
# Verify recovery on this Device.

For multi-Device rollback, repeat per Device. The fleet is in mixed state until rollback finishes.

Hot deploys ​

Some changes are runtime-record-only (e.g., adding a new runtime, changing a port). These do not require a full wrapper upgrade:

bash
matrix invoke host.control runtimes.declare '{"runtimeId":...}'
matrix invoke host.control runtimes.start '{"runtimeId":...}'

The supervisor reconciles. No restart of the supervisor itself is needed.

Upgrade the platform Host vs upgrade a user Device ​

The same procedure works for both. The platform Host upgrade has additional considerations:

  • All paired Devices may briefly lose bus connection while the platform NATS restarts.
  • Sessions remain valid (HMAC signed by the unchanged secret).
  • Browser users may see momentary "connection lost" UI; reconnects automatically.

Schedule platform upgrades during low-traffic windows.

Target: rollout dashboard ​

Per WORKSTREAMS/docker-npm-parity/, the target is a rollout orchestrator (see Dashboard: Deployments) that:

  • Drives upgrades from the platform Host outward via host.control ops.
  • Phases the rollout (canary → bulk → full).
  • Health-gates between phases.
  • Auto-rollback on health-gate failure.
  • Audit-logs every transition.

The plumbing (per-Device host.control, runtime records, system.devices visibility) exists. The orchestrator does not.

Pre-deploy checklist (manual) ​

Before starting any rollout:

  • [ ] Tested the new version end-to-end in a non-production Host.
  • [ ] Identified canary Device.
  • [ ] Confirmed rollback wrapper version available (don't delete the old apt repository entry yet).
  • [ ] Notified affected users of maintenance window.
  • [ ] Have a kill switch ready (script to revert all upgraded Devices).

See also ​

Source: WORKSTREAMS/docker-npm-parity/. Today's procedure is operator-experience captured in the P1.22 progress log.