Control plane deploy
How the HostSSH control plane itself is built, published, and swapped. Pushing main does not deploy it.
Control plane deploy
There are two deploys in this repository. They are easy to mix up, and mixing them up ships the wrong story.
| App deploy | Control plane deploy | |
|---|---|---|
| What moves | A customer's app, onto a Node | This Next.js app, hostssh-cp |
| Who starts it | The agent, from hostssh deploy or a queued job | An operator, on the hub node |
| What "push" means | A git push can build that app, when a webhook or hook is configured for it | A git push publishes the control-plane source. It does not swap the running container. |
App deploy is Deploy pipeline. This page is only the control plane.
Sources: control-plane/web/Dockerfile, scripts/node/redeploy-hostssh-cp.sh, control-plane/web/lib/migrations/list.ts, control-plane/web/lib/migrations/runner.ts. The operator procedure also lives in .claude/skills/hostssh/SKILL.md. Where this page and that skill disagree, re-read the script before you run it.
What the running process is
The control plane is a Next.js app with output: 'standalone'. The image runs node server.js. The Docker build context is control-plane/web only. Files outside that directory, including control-plane/db/*.sql and the repo-root docs/ tree, are not in the image.
That is why schema changes that must apply on boot are TypeScript or JavaScript modules in control-plane/web/lib/migrations/, imported by list.ts. See Database and migrations.
Docs are compiled into control-plane/web/lib/docs/content-index.json before the image is built (scripts/build-docs-index.mjs). The container serves that JSON. Editing a markdown file in git does not change the live site until a new image is built and the operator swaps it.
What a git push does
main on GitHub is the published source. GitHub Actions workflows are parked under .github/workflows-disabled/. A push does not build the production container and does not apply migrations.
Check the published commit:
git rev-parse HEAD
git rev-parse origin/main
Check the running commit, on the app node, inside the container:
docker exec hostssh-cp printenv SOURCE_COMMIT
Those two SHAs are allowed to differ. The difference means "published and not yet swapped." It is not a failed deploy.
Point-in-time reading, 2026-11-03, written in planning/NOW.md:
| SHA | |
|---|---|
main | e32f292468c4104a1f9fe8bf8db2f22c159567f1 |
SOURCE_COMMIT | 584e9a8709264c14d3952f01bb41ff6a88472c14 |
That row goes stale the moment someone redeploys. Read the live value. Do not quote this table as the current production pin.
What the operator runs
The script in git is scripts/node/redeploy-hostssh-cp.sh. On the hub node the copy that matches this repo is /root/redeploy-hostssh-cp.sh. Older copies have lived at /usr/local/bin/ and /srv/hostssh-cp-src/. Compare checksums before you run one. The skill records a check on 2026-10-19 that the /root copy matched the repo and the other two were older. Re-check. Do not trust that date forever.
The redeploy is owner-run. It builds the image and, when the new process boots, the migration runner applies any pending migration. That is a production database change. This page does not include the SSH commands. Use the skill when you have decided to swap.
/healthz is the public check that the process is serving:
200means the process considers itself ready.503means the database, the schema, or the migrations have not converged.- The JSON includes the migration count, for example
58/58and the id0058_fleet_alert_outboxwhen this list is fully applied.
The list in list.ts ends at 0058_fleet_alert_outbox (lib/migrations/0058-fleet-alert-outbox.js). A health payload whose count does not match the list in the image you just built means that image is not the one you think.
Boot order, short version
- The operator stages the exact git commit, not a dirty working tree.
- The node builds the standalone image.
- The new container starts.
instrumentation.tsfiresrunMigrations()without awaiting it insideregister(), so a slow migration does not block the process from listening./healthzreports pending until the runner finishes. Detail is in Database and migrations.- The runner uses
MIGRATIONS_DATABASE_URLwhen it is set, otherwiseDATABASE_URL. DDL has to run ashostssh_migrator. The runtime rolehostsshis DML only. - You compare
SOURCE_COMMITto the SHA you staged, and you read/healthz.
A migration whose checksum changed after it was applied is drift. The runner logs it and does not re-run it. Fix forward with a new migration id. Do not edit a shipped file.
Env that this deploy cares about
Names only. Values stay on the node, in the env file the redeploy merges. Never commit them.
| Key | Role |
|---|---|
DATABASE_URL | Runtime role hostssh. |
MIGRATIONS_DATABASE_URL | Schema owner hostssh_migrator. |
SOURCE_COMMIT | The git SHA the image was built from. The redeploy sets it. |
HOSTSSH_ALERT_OUTBOX_ENABLED | 1 turns on the durable alert outbox. Unset or any other value leaves it off (lib/notifications/outbox-store.js). |
HOSTSSH_LICENSE_PRIVKEY | Required for /v1/license/activate to sign. Unset returns 503 from that route. |
CRON_SECRET | Gates cron routes. Header only. |
The full key list for local work is Environment and secrets.
Rollback
Keep the previous image until the new /healthz is ok and SOURCE_COMMIT matches the SHA you staged. The redeploy script is the supported swap. A hand-edited container that is not built from a SHA will not match the next health check you write down.
If migrations applied and you need to undo them, write a new forward migration. The runner does not walk backward.
Docs on the live site
/docs/user/... and /docs/dev/... render from content-index.json, and from the docs table when that table has been ingested and DATABASE_URL is set (lib/docs/store.ts). The table is optional. The JSON is the build-time source.
Rebuild the index after a markdown change, from control-plane/web:
node scripts/build-docs-index.mjs
node scripts/build-chat-index.mjs
predev and prebuild run the docs index. A Docker build whose context cannot see docs/ keeps the committed index instead of replacing it with an empty list. That guard is in build-docs-index.mjs. Do not delete it.
Ingest into Postgres, for a live edit that does not wait on a redeploy, is scripts/ingest-docs.mjs. That writes the database. It is an owner step. This page does not run it.