Skip to content

docs: align deployment docs with the live host and shipped firmware (closes #242, closes #252) - #282

Merged
cofade merged 7 commits into
mainfrom
docs/242-252-deployment-docs-consistency-sweep
Sep 24, 2026
Merged

cofade merged 7 commits into
mainfrom
docs/242-252-deployment-docs-consistency-sweep

Conversation

@cofade

@cofade cofade commented Sep 10, 2026 •

Copy link
Copy Markdown
Collaborator

References the umbrella docs epic #200 and the 2026-08 audit epic #262. The audit's #275 and #281 remain open after this PR — it documents their current state but addresses neither of them.

What changes

The deployment chapter labelled the path the live host actually runs (Nginx + PM2) "non-recommended legacy" and presented the never-deployed Docker topology as the production path. This PR flips that, and reconciles the rest of the chapter with the shipped firmware and the measured test/CI state.

Stays open after this PR

Verification

  • The 9-gate pre-push battery in a node:22 container: 8 PASS, 1 self-SKIP (check-duckdb-bind-claims needs the docker CLI; the ubuntu-latest CI job covers it).
  • check-doc-citations: 7 OK, 0 problems. check-env-var-docs: 14/14.
  • Every quantitative claim (test counts, suite and CI-job counts) was re-measured live from this branch during review, not copied from memory.
  • Every wire-shape claim was cross-checked against image-service/app.py, duckdb-service/routes/modules.py, duckdb-service/db/schema.py, and the ESP32-CAM sources (build.sh, ota.cpp, tls_roots, form_query).

References #242, #252, #200.

Deployment-docs consistency sweep: make the in-repo docs describe the
runtime the live host actually runs (bare-metal Nginx + PM2 behind a
Caddy edge, no Docker) instead of a mix of the two supported
topologies, and keep that description mechanically current.

New:
- docs/07-deployment-view/what-is-live.md: one-page "which runtime is
  live" reference - host verification probes, runtime matrix, and the
  production env-var matrix (14 vars x per-runtime where-set x unset
  semantics), with the PM2/Docker port-mirror footgun called out.
- scripts/check-env-var-docs.sh, wired into the Makefile, the husky
  pre-push hook, and the CI repo-guards job (ci-gates.md updated):
  every env var declared in .deploy.env.example,
  .env.production.example, or docker-compose.prod.yml must have a row
  in that matrix - the #201/#242 failure mode was a variable living in
  exactly one file with no document mapping it.

Corrections:
- Nginx vhost rows: the main domain carries no API of its own (its
  /api/ falls into the SPA); the browser API is on the
  api.highfive.schutera.com subdomain behind the Caddy edge.
- production-runbook.md Environment Configuration: rewritten around
  the live PM2 env layout (gitignored .env/.deploy.env/
  ecosystem.config.js), with the .env.production template demoted to
  the Docker target; .env.example and .env.production.example
  comments corrected (VITE_API_URL carries the /api suffix, backup
  defaults follow the code).
- BACKUP_DIR/BACKUP_KEEP code defaults (dirname(DUCKDB_PATH)/backups,
  keep 4) in duckdb-service.md and ADR-031.
- ADR-008 addendum: the public-origin OTA fetch relies on the pinned
  ISRG + GTS root bundle; an on-path attacker cannot inject a manifest
  without compromising the TLS-verified origin itself.
- image-service: raw-SQL passthrough removed from services/duckdb.py;
  vestigial DUCKDB_PATH entries removed from the test compose files
  (image-service never reads it); PORT comment corrected (DEFAULT_PORT
  is 3002, not 3001).
- AGENTS.md/CLAUDE.md: firmware release section split into manual and
  automated (FIRMWARE_AUTO_OTA) modes with a what-is-live.md link;
  test counts updated.
- New ch.11 open-issues row: the public GET /api/modules payload
  carries the firmware-reported email (decision pending: strip or
  document in auth.md).
- Remaining audit wording fixes across the arc42 chapters,
  api-reference.md, auth.md, api-contracts.md, the glossary, and
  CONTRIBUTING.md.
The husky pre-commit hook runs `npx lint-staged`, and `npx` only exists
with a Node install. A checkout whose node_modules was created inside a
Linux container has no host Node, so every commit dies in the hook.
The entry gives the durable fix (winget Node 22) and a one-off fix
(run the commit, and if needed the push, from a node:22 container;
gh token passed via the remote URL).
The two-mount variant of the commit one-liner (repo + %TEMP%) loses
the message file inside the container on Docker Desktop for Windows:
heavy writes to the repo share hide files on the other share from the
container. The entry now stages the message in .git/COMMIT_MSG_TMP on
the single repo mount (verified end to end). The push one-liner gains
the git install its node:22 base image lacks, and injects
user/token/branch through env vars instead of a quoted URL.
The banner linked #5b-espota-ingress-port-80, but the section heading
is "5b. ESP/OTA Ingress (both ports)", so GitHub's anchor is
#5b-espota-ingress-both-ports. Found during the final review of the
#242/#252 docs-consistency sweep; every other claim in the branch
checked out against the code.
@cofade

cofade commented Sep 10, 2026

Copy link
Copy Markdown
Collaborator Author

This entire PR has been created by Qwen3.8:27B running on sustainable energy on my local RTX 3090 GPU.

Captures the observed 400 and 422 failures from Invoke-RestMethod and the verified node:22 fetch workaround.
- Correct the what-is-live relative link in the ADR-008 addendum.
- Correct the adjacent glossary link in api-reference.
- Record the verified closure dates for the removed ch.11 issue rows.
- State that gh auth token is long-lived and must be revoked, not short-lived.
- Distinguish process-argv visibility from container-environment visibility.
@cofade
cofade marked this pull request as ready for review September 16, 2026 19:27
@cofade
cofade requested a review from schutera September 16, 2026 19:28
@cofade
cofade merged commit d2f4bc4 into main Sep 24, 2026
23 checks passed
@cofade
cofade deleted the docs/242-252-deployment-docs-consistency-sweep branch September 24, 2026 20:53
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.

1 participant