Porter deployment onboarding: checklist, deploy reference, first-admin guardrails - #911
Merged
Conversation
16francej
force-pushed
the
porter-onboarding
branch
from
September 3, 2026 01:46
2d18d35 to
0284bbb
Compare
…rdrails Porter had no onboarding path: docs/porter.md was post-hoc field notes, the cloud-account prerequisite appeared nowhere in the repo, the Admin-vs-Developer token requirement was stranded 180 lines below where the token is introduced, the porter CLI was used but never declared, and ADMIN_GRANTS — without which a Postgres-backed instance boots with a permanently unreachable admin console — was missing from the Porter path entirely. - docs/porter.md gains an onboarding checklist up top: linked cloud account (with the region-SCP and account-ID field gotchas), Admin-role API token, sandbox ingress in the creation contract, administrator email before first boot, then build/apply/verify — with agent-with-browser vs hand-the-operator- the-URL guidance. - cli/templates/deployment/references/porter.md (+ .codex stub) brings Porter into the deployment workflow following the fly.md/aws.md pattern, and deployment.md's provider choice now names Porter with its manual path. - PORTER_DEPLOY_API_TOKEN's secret spec names the Admin-role requirement and gains a generate hint pointing at the dashboard. - Core boot warns when a durable store has no ADMIN_GRANTS, naming the first-admin lockout and its fix. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…ions
From a live Porter test deployment on main:
- Auth misreported a core outage as "per-address rate limit reached":
coreClaimStore mapped every transport failure and 5xx to null, which
withinRateLimit read as an exhausted slot. The claim store now throws a
typed ClaimStoreUnavailableError; sign-in still fails closed but says core
is unreachable, link verification answers a retryable 503 ("temporarily
unavailable", link stays valid) instead of the dead-end stale-link page,
token exchange answers temporarily_unavailable, and the playground mint
keeps its 429 with an honest log. Auth gains /readyz, which probes core's
/healthz so orchestrators can gate traffic on the dependency.
- docs/porter.md no longer claims Porter creates the Route53 hosted zone —
confirmed against Porter's team and live DNS that the dedicated zone, NS
delegation, and wildcard record are the operator's to create, with the
reconcile step that then mints the issuer.
- Onboarding checklist and porter reference gain the DATABASE_URL step
(sign-in hard-requires the durable store; no CLI provisioning on Porter;
API-created RDS can name the cluster in connected_cluster_ids while its
security group refuses it), the porter-dev tap vs Homebrew-core `porter`
collision plus docker-credential-porter, app-level env in v2 YAML, and
ECR repositories not auto-created on push.
- porter/apps/egress-proxy.yaml documents why it is a worker and what makes
egress enforced rather than fail-open (LoadBalancer in front, sandboxes
cannot reach RFC1918 and the web ingress cannot carry CONNECT).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
16francej
force-pushed
the
porter-onboarding
branch
from
September 3, 2026 03:50
3ff3e5e to
e88d098
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Stacked on #910 (it extends the same docs/porter.md; retarget to main once #910 merges).
Why
First-hand Porter onboarding feedback: nothing tells a new operator (or the deploying agent) to link a cloud account, which token role to mint, or to name an administrator — and with Postgres, a missed
ADMIN_GRANTSyields a running instance whose admin console can never be unlocked from inside the product. TheporterCLI is used throughout the docs without ever being declared a prerequisite.What
docs/porter.md: cloud account linked (checkGET .../cloud-accountsfirst, prompt the operator to link at dashboard.porter.run/cloud-accounts if not — with the us-east-2 SCP and account-ID gotchas), Admin-role API token (Developer tokens die mid-deploy withPERMISSION_DENIED), sandbox ingress in the creation contract, administrator email before first boot, then build/apply/verify. Written for agents: use the operator's browser for dashboard steps when available, otherwise hand over the exact URL; prefer theporterCLI over raw API calls.references/porter.mdin the deployment workflow (mirroringfly.md/aws.md, plus the.codexstub), and Porter added todeployment.md's hosting-target choice with an honest note that it has noqmCLI target.PORTER_DEPLOY_API_TOKENnow says Admin-role and carries a generate hint (dashboard → Settings → API tokens).DATABASE_URLis set with noADMIN_GRANTS, naming the first-admin lockout and the exact fix.Verification
test/deployment-skill.test.tsextended (porter reference phrases, file presence in both reference dirs, workflow routing);cli/test/package.test.tspins the new template in the published package; clisecrets/initsuites,public-architecture-docs, typecheck, eslint, oxlint, prettier all green locally.🤖 Generated with Claude Code
Need help on this PR? Tag
@codesmith-botwith what you need. Autofix is disabled.