Skip to content

docs(readme): document bootstrap-admin for a production host - #418

Merged
mforce merged 1 commit into
mainfrom
docs/bootstrap-admin-production-form
Aug 4, 2026
Merged

mforce merged 1 commit into
mainfrom
docs/bootstrap-admin-production-form

Conversation

@mforce

@mforce mforce commented Aug 4, 2026

Copy link
Copy Markdown
Owner

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

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

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 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".

Comment thread README.md
Comment on lines +73 to +75
docker run --rm --env-file <owner-credential.env> \
ghcr.io/mforce/cluckwork@sha256:<digest> \
bootstrap-admin --email admin@example.com

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge 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 👍 / 👎.

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@mforce
mforce merged commit 72ef8db into main Aug 4, 2026
9 checks passed
@mforce
mforce deleted the docs/bootstrap-admin-production-form branch August 4, 2026 07:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

README: bootstrap-admin is documented only for a dev box, not a published image

2 participants