Repository navigation
docs(readme): document bootstrap-admin for a production host - #418
Conversation
The README documented `bootstrap-admin` only in dev-box forms — the repo's `deploy/docker-compose.yml` stack and a `dotnet run` from source. Neither exists on a production host, so an operator following it gets `dotnet: command not found` (what happened on the 2026-08-03 rollout). Add a "Provisioning the first admin on a production host" subsection with the portable `docker run --env-file <owner-credential.env> <image@digest> bootstrap-admin` invocation, stating the credential requirement as one fact: the env file must carry the migrator/owner credential (the #263 role split), not the runtime role, because the verb migrates before it creates the Owner and the runtime role has no DDL. Keeps the "pass the verb only" note adjacent and notes why the dev forms don't transfer (no pinned address; one credential for everything). Nothing host-specific — that stays in the deployment repo. Closes #414. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LSkqgsC9Sj4arUdevUSJfJ
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 9a80e69ed1
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| docker run --rm --env-file <owner-credential.env> \ | ||
| ghcr.io/mforce/cluckwork@sha256:<digest> \ | ||
| bootstrap-admin --email admin@example.com |
There was a problem hiding this comment.
Attach the bootstrap container to the database network
When production Postgres is reachable only through a deployment-internal network—as in the repo's private-bridge topology where the connection uses Host=db—this standalone docker run joins neither that network nor its DNS namespace, so bootstrap-admin fails before provisioning. Add a portable network-access prerequisite or a --network <deployment-network> placeholder while leaving the concrete network value to the deployment repo.
AGENTS.md reference: AGENTS.md:L78-L87
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
From the deployment side: this specific scenario (a co-located Postgres container reachable only by a compose service name, e.g. Host=db) doesn't apply to how we run production — our database isn't a container on this host, so there's no compose-internal DNS name for a standalone docker run to fail to resolve.
The general prerequisite you're pointing at — this container needs a working path to the database — is still real for us, it's just satisfied at the host level rather than by joining a specific Docker network, so a --network <deployment-network> placeholder wouldn't map onto our setup even generically.
Given the doc already scopes network layout as host-specific, I'd read this finding as most applicable to topologies that also co-locate Postgres as a container. We'll cover our own case in our own deploy-side runbook rather than here.
The README documented
bootstrap-adminonly in dev-box forms — the repo'sdeploy/docker-compose.ymlstack and adotnet runfrom source. Neither existson a production host, so an operator following it gets
dotnet: command not found(what happened on the 2026-08-03 rollout).Add a "Provisioning the first admin on a production host" subsection with the
portable
docker run --env-file <owner-credential.env> <image@digest> bootstrap-admininvocation, stating the credential requirement as one fact:the env file must carry the migrator/owner credential (the #263 role split),
not the runtime role, because the verb migrates before it creates the Owner and
the runtime role has no DDL. Keeps the "pass the verb only" note adjacent and
notes why the dev forms don't transfer (no pinned address; one credential for
everything). Nothing host-specific — that stays in the deployment repo.
Closes #414.
Co-Authored-By: Claude Opus 4.8 noreply@anthropic.com
Claude-Session: https://claude.ai/code/session_01LSkqgsC9Sj4arUdevUSJfJ