Repository navigation
docs: align deployment docs with the live host and shipped firmware (closes #242, closes #252) - #282
Merged
Conversation
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.
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.
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
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.
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.
what-is-live.md(new,docs/07-deployment-view/) — one-page answer to "which runtime is live": runtime matrix (PM2 live, Docker target not yet deployed), 14-variable env-var matrix with per-runtime sources, 30-second verification block (probes, not assumptions).production-runbook.mdbecomes "the path live in production";production-deployment.mdbecomes "supported target, not yet deployed".location =blocks for/upload,/new_module,/heartbeat,/firmware.json,/firmware.app.binon:443(the fleet since security: migrate ESP <-> server traffic from HTTP to HTTPS (server already supports it) #79 speaks TLS, ADR-010) and:80(pre-security: migrate ESP <-> server traffic from HTTP to HTTPS (server already supports it) #79 stragglers + LAN-dev builds). The port-mirror footgun is documented (PM2 native ports image:4444/ duckdb:8000vs Docker host ports image:8000/ duckdb:8002).Server: Caddy), browser API on theapi.highfive.schutera.comsubdomain (main-domain/api/falls into the SPA),/firmware.jsonand/firmware.app.bin404 on both ports — the setup wizard cannot flash a new module and noSEQUENCE-bumped OTA release (including the firmware: setTimeout() unit bug (seconds on core 2.0.17), captive-portal loops without deadline/WDT feed, and a fixed OTA download deadline — one SEQUENCE-bumped release #231 fix) can reach the fleet until setup wizard cannot flash on production: /firmware.bin, /firmware.app.bin and /firmware.json are all missing from the live host #275 lands.RUN_TESTs / 20 suites, 13 Playwright specs, 15 CI jobs intests.yml); theapi-referenceupload envelope now matches the actualmac-branching responses;GET /modulesdocumented with its explicit column list, thereal_image_count/last_image_atjoin, and the unauthenticatedemailexposure (pending decision); the shelved weather/battery charts noted in ADR-015;build.shdocumented as arduino-cli-based (not PlatformIO) with themin_spiffsmirror; theVITE_API_URL/apisuffix made mandatory in.env.example;.env.production.examplebackup defaults corrected todirname(DUCKDB_PATH)/backups.scripts/check-env-var-docs.sh(the security: rotate + de-hardcode the committed Discord webhook default in duckdb-service #201 failure mode: a production env var living in one file with no matrix row), wired into the Makefile, the pre-push hook, and therepo-guardsCI job..git/COMMIT_MSG_TMPpattern), plus a Windows PowerShell 5.1 entry forInvoke-RestMethodnon-ASCII GitHub API JSON and the verifiednode:22fetchworkaround.Stays open after this PR
homepage/dist(operational, on the host).Verification
node:22container: 8 PASS, 1 self-SKIP (check-duckdb-bind-claimsneeds the docker CLI; the ubuntu-latest CI job covers it).check-doc-citations: 7 OK, 0 problems.check-env-var-docs: 14/14.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).