Operate
Day-2 on-prem is deliberately boring: the installer is also the repair tool, every error tells you what to do, and the seal check tells you when you're done. There is no separate runbook to memorize.
kapable-ops --helpYou should see the operator command list.
Healing: re-run the installer
The bootstrap graph is idempotent, so the repair procedure
for almost anything is the install command itself. A config
file hand-edited into a bad state, a service unit removed, a missing
database — re-run the full command and watch the outcomes: nodes
that find drift report APPLIED (found and fixed), the
rest report NO-CHANGE. Finish with
--seal-check for the receipt.
Re-running is safe while the platform is serving: nodes verify before they touch anything, and a converged system takes about five minutes to walk with zero changes.
Errors are instructions
Platform error messages name the limit or cause and the corrective action, in the message itself. This is a design rule, not an aspiration — the intended reader of an error is whoever (or whatever) will act on it, including your AI assistant. When something fails: read the error, do what it says, re-run. If an error ever leaves you guessing, that is a bug worth reporting.
Upgrades
An upgrade is the same motion as an install: obtain the newer
artifact bundle for your license (see
distribution),
point --artifact-source at it, and re-run. Nodes whose
artifacts changed redeploy them (APPLIED); everything
else is NO-CHANGE. Deploys go through Berth's
blue-green slots, so services swap without dropping the box.
Run --seal-check after.
Backups
Three things on the box constitute your state; everything else is reproducible from the installer and your artifact bundle:
| What | Where | How |
|---|---|---|
| PostgreSQL | all platform data | pg_dumpall on a schedule you trust; standard PITR tooling applies. Restores have been exercised across major PG versions with a plain dump/restore. |
| Service env files | /opt/kapable/env/ | Contains the box-local secrets generated at install (node 2). Back up encrypted; without them a restore regenerates secrets and re-issues sessions. |
| Owner credentials | /root/.kapable-bootstrap/ | The first-org owner login persisted at install, mode 0600. Store it in your password manager and you can delete it from the box. |
Where things live
| Path | Contents |
|---|---|
/opt/berth/ | The deploy orchestrator: slots, per-service signing keys, service logs under data/logs/. |
/opt/kapable/env/ | Per-service environment files (secrets; mode-restricted). |
/etc/caddy/ + /etc/caddy/conf.d/ | The TLS edge. conf.d snippets are generated by the gateway service from its database — hand-edits are overwritten within a minute by design. Routing changes go through the platform, not the files. |
/var/lib/postgresql/ | The database cluster. |
Next Steps
Verify
The seal check as your standing health probe.
Troubleshooting
Platform-wide diagnostic patterns.
Overview
Back to the start of the on-prem section.