docs: hosting topology for humans and machines - #332
Merged
Conversation
Adds the missing map of where ECHIDNA actually runs, in both registers: - docs/HOSTING.md — the three public surfaces (Cloudflare Pages for the site, Hetzner behind Caddy for the API, Cloudflare Email Routing for contact), how each is built, and the two constraints that bite when editing the site: the SSG hard-fails on a11y violations, and its copyTree is text-only so binaries need cp. - .machine_readable/deployment.a2ml — the same topology as structured data, including the API's limits and the risks of exposing an unauthenticated service that spawns provers on user input. Both record the two current blockers honestly: repository-wide Actions startup_failure (a minimal probe workflow fails identically, so it is not a workflow-file fault), and an apex that resolves to Cloudflare but has no origin behind it. Both also carry the diagnostic that keeps catching people out: a workflow which fails at startup registers no check run, so gh pr checks reports success while every gate is dead — and a workflow listed by path rather than name has never been parsed. docs/deployment/DEPLOYMENT_GUIDE.md is reduced to a superseded stub. It described a 2025-11 v0.1.0 deployment whose next step was 'deploy to GitLab', referenced an unrelated migration, and quoted a fixed prover count that the canonical-reference policy forbids in prose. Kept as a stub so existing links do not dead-end. Verified: .githooks/validate-a2ml.sh passes (exit 0) with the new manifest present. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
Note Automatic reviews are paused because your trial's included automatic processing has been used for this period. Upgrade now, or comment "Gitar review" to run a review anytime. Code Review ✅ ApprovedDocuments the production hosting topology for both human readers and machine consumers in HOSTING.md and deployment.a2ml, while neutralizing outdated deployment guides. No issues found.
OptionsDisplay: compact → Showing less information. Comment with these commands to change the behavior for this request:
Was this helpful? React with 👍 / 👎 | Gitar |
![gitar-bot[bot]](https://avatars.githubusercontent.com/in/827041?s=60&v=4){kind=small}
hyperpolymath
disabled auto-merge
July 29, 2026 07:29
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.
Documents where ECHIDNA actually runs — the map that was missing after the site and deploy work landed in #329/#330.
What's here
docs/HOSTING.md(humans) — the three public surfaces and how each is built:nesy-prover.dev— websitepages.yml(Ddraig SSG)api.nesy-prover.dev— HTTP APIsudo@nesy-prover.dev— contactIt also captures the two site constraints that bite when editing: the SSG hard-fails the build on any a11y violation (more than one
h1, a skipped heading level, a missingalt), and itscopyTreeis text-only and corrupts binaries — which is why the playground has a separatecpstep..machine_readable/deployment.a2ml(machines) — the same topology as structured data, including the API's limits (30/min/ip, 1 MB body,--memory=1500m --pids-limit=512, no published host port) and an explicit risk block: the API has no authentication and spawns prover binaries on user input, rate limiting bounds request count rather than the cost of one request, and a per-request prover timeout is outstanding.Honest about what is broken
Both files record the two live blockers rather than describing an aspirational happy path:
startup_failure— every workflow, includingpages.yml. A minimal probe workflow containing one SHA-pinnedactions/checkoutfails identically, so this is not a workflow-file fault.nesy-prover.devresolves to Cloudflare, the TLS handshake completes, and the request then hangs. The DNS records are likely already right; the Pages project behind them is what is missing.Both also carry the diagnostic that keeps costing time here: a workflow that fails at startup registers no check run, so
gh pr checksreports success while every real gate is dead — and a workflow listed by path instead of name has never been parsed.Stale doc neutralised
docs/deployment/DEPLOYMENT_GUIDE.mdbecomes a superseded stub. It described a 2025-11 v0.1.0 deployment whose next step was "deploy to GitLab", referenced an unrelatedzotero-voyant-exportmigration, and quoted a fixed prover count that the canonical-reference policy forbids in prose. Kept as a stub so existing links don't dead-end.Verification
.githooks/validate-a2ml.shpasses (exit 0) with the new manifest present — the same validator the dogfood gate runs.Note that CI cannot verify this PR: see blocker 1 above.