Operator · Troubleshooting Your Environment

Startup Refusals

Frame 100 of 107

A deployment that will not come up is usually refusing on purpose. The diagnostic order:

Services never become healthy — check the migration job first: docker compose logs goca-db-migrate. A checksum error means an applied migration file changed; restore the original file — applied migrations are immutable.

A fresh split deployment crash-loops on password authentication — the roles job has not run, or ran with different passwords than the service DSNs carry; re-running it rotates to current values.

A role listens but does nothingkeysvc, issuer, ra, crlgen are health-only listeners today; not a fault.

A warning that a DSN is set but unused — the console and protocol heads reach everything over the API; a database credential left on them is an unused credential the process still opens a pool for. Remove it.

The process exits naming GOCA_KEY_CUSTODY and keysvc — deliberate protection: only keysvc may create CA keys, so continuing would boot with no hierarchy and every listener on a fallback certificate — which looks like a TLS fault and is not one. Add the role or unset the variable.

Now I can read a refusing boot instead of restarting it harder.