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 deployControl plane deploy
What movesA customer's app, onto a NodeThis Next.js app, hostssh-cp
Who starts itThe agent, from hostssh deploy or a queued jobAn operator, on the hub node
What "push" meansA git push can build that app, when a webhook or hook is configured for itA 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
maine32f292468c4104a1f9fe8bf8db2f22c159567f1
SOURCE_COMMIT584e9a8709264c14d3952f01bb41ff6a88472c14

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:

  • 200 means the process considers itself ready.
  • 503 means the database, the schema, or the migrations have not converged.
  • The JSON includes the migration count, for example 58/58 and the id 0058_fleet_alert_outbox when 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

  1. The operator stages the exact git commit, not a dirty working tree.
  2. The node builds the standalone image.
  3. The new container starts.
  4. instrumentation.ts fires runMigrations() without awaiting it inside register(), so a slow migration does not block the process from listening. /healthz reports pending until the runner finishes. Detail is in Database and migrations.
  5. The runner uses MIGRATIONS_DATABASE_URL when it is set, otherwise DATABASE_URL. DDL has to run as hostssh_migrator. The runtime role hostssh is DML only.
  6. You compare SOURCE_COMMIT to 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.

KeyRole
DATABASE_URLRuntime role hostssh.
MIGRATIONS_DATABASE_URLSchema owner hostssh_migrator.
SOURCE_COMMITThe git SHA the image was built from. The redeploy sets it.
HOSTSSH_ALERT_OUTBOX_ENABLED1 turns on the durable alert outbox. Unset or any other value leaves it off (lib/notifications/outbox-store.js).
HOSTSSH_LICENSE_PRIVKEYRequired for /v1/license/activate to sign. Unset returns 503 from that route.
CRON_SECRETGates 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.

Control plane deploy — HostSSH Docs