hostcd — operations (day two)

Upgrades

hostcd upgrades server-first: upgrade hostcd-server, then the agents. The protocol is version-compatible across a release, so a newer server speaks to older agents during a rollout. Re-running the installer swaps the binary and restarts the unit.

Upgrade an agent by re-running the agent install (or swapping the verified binary and systemctl restart hostcd-agent); the token in /etc/hostcd/agent.env is preserved, so there is no re-enrolment.

One-click self-update (opt-in)

Because the server runs unprivileged it cannot replace its own binary, so one-click update is off by default. Enable it at install time with HOSTCD_SELF_UPDATE=1 (cosign must be installed on the host — it is mandatory for the unattended root updater). This adds:

a root hostcd-update.service oneshot that re-runs the signed installer;
a root hostcd-update.path unit that starts it when the server writes a trigger file;
HOSTCD_UPDATE_COMMAND in server.env.

With it enabled, the UI shows the running version in the sidebar, a What's new panel with the release notes, and an Update now button. Clicking it pins the latest tag, verifies the installer's cosign provenance and checksum, swaps the binary, and restarts — the UI waits and reloads on the new version. The manual install command stays available either way.

Backup and restore

The Backup screen exports the full server state (applications, hosts, projects, users, settings) to a file, and restores from one. Keep a periodic export; the Recovery screen shows when the last export ran.

High availability (Enterprise)

With the Postgres backend, run multiple servers: reads are served anywhere and writes go through an elected leader (writes from a standby are forwarded). The Recovery screen shows HA and leadership status.

Metrics

/metrics exposes Prometheus metrics (host online/offline counts, app sync state, and more). On an untrusted network protect it with -metrics-token; the Security screen flags when it is open.

A typical change

Commit a manifest change to the app's Git folder and push.
hostcd shows the app Out of sync with a diff (the preview).
For a gated (approval-required) app, one admin requests the sync and a different admin approves; otherwise it applies on sync or automatically.
The rollout runs host by host; the result is recorded in history and sent to any webhook and audit sink.
If something is wrong, roll back to the previous revision from the UI.

Next: overview · concepts · security.

This page is also available as Markdown, indexed in llms.txt for AI assistants.