4.4 KiB
4.4 KiB
schema_version, id, type, scope, sensitivity, last_reviewed, sources, related, update_triggers, unknowns
| schema_version | id | type | scope | sensitivity | last_reviewed | sources | related | update_triggers | unknowns | |||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 1 | home-server.notes | reference |
|
private-infrastructure | 2026-10-27 |
|
|
|
|
Notes publication
Repository intent; recovery from the previously failed deployment is unconfirmed.
---
config:
themeCSS: |
text,.nodeLabel { fill:var(--infra-text);color:var(--infra-text); }
.edgeLabel,.edgeLabel p { background:var(--infra-zone);color:var(--infra-text); }
.flowchart-link { stroke:var(--infra-line); }
marker path { fill:var(--infra-line);stroke:var(--infra-line); }
.infraClient rect { fill:var(--infra-client-fill);stroke:var(--infra-client-stroke);rx:8px;ry:8px; }
.infraEdge rect { fill:var(--infra-edge-fill);stroke:var(--infra-edge-stroke);rx:8px;ry:8px; }
.infraStorage rect,.infraStorage path { fill:var(--infra-storage-fill);stroke:var(--infra-storage-stroke); }
.infraService rect { fill:var(--infra-service-fill);stroke:var(--infra-service-stroke);rx:8px;ry:8px; }
---
flowchart LR
accTitle: Signed webhook to built documentation
accDescr: Gitea queues a signed push; a single builder writes the shared static volume; nginx serves it read-only.
Git["Gitea push<br/>main"]:::infraClient
Builder["notes_builder :9000<br/>HMAC check / queue / build"]:::infraEdge
Static[("notes_static<br/>generated site")]:::infraStorage
Web["notes_web :8080<br/>read-only nginx"]:::infraService
Git -->|"Signed POST"| Builder -->|"/site-output"| Static -->|"/usr/share/nginx/html"| Web
- Web:
https://notes.umbra.mom, Traefik + Authentik forward-auth. - Clone source:
http://gitea:3000/jay/notes.git; requireszensical.toml,pyproject.toml,uv.lock. - Listener
/builder/listener.pychecksX-Gitea-SignaturewithWEBHOOK_SECRET. - 202 = queued, not built. Single worker logs
Documentation build succeededafter generatedindex.html. - Publication replaces volume contents non-atomically; brief missing files possible. Starting an empty builder does not trigger a build.
uv run --locked zensical build --clean --config-file zensical.toml
Networks and webhook allowlist
| Setting | Value |
|---|---|
| Build network | notes_build, Gitea-owned / external to Notes; 10.90.0.0/29 |
| Builder IP / webhook | 10.90.0.3; http://notes_builder:9000/ |
| Gitea setting | GITEA__security__ALLOWED_HOST_LIST="10.90.0.3:9000" |
| Web network | notes_web on traefik; builder not attached |
- Gitea 28 requires resolved private IP allowlisting; hostname alone failed. Do not broadly allow private networks.
- Recheck subnet collisions on recovery; old
172.30.90.0/29overlapped Actions'172.30.0.0/16. - Build network is non-internal: dependency installation requires outbound access.
Deployment
- Push stack changes; preserve Portainer values. Copy listener/nginx config into
/data/notes/{listener.py,nginx.conf}; Git pull does not update binds. - Set matching
WEBHOOK_SECRETin Notes and Gitea's push webhook; retain the internal webhook URL. - Redeploy Gitea first; confirm
notes_buildhas the expected subnet/allowlist. - Redeploy Notes outside an active build; preserve
notes_static, never remove volumes. - Wait for healthy Gitea and builder
Listening on 9000; redeliver the webhook. - Confirm 202, build-success log and authenticated updated page.
Health / troubleshooting
- Web probe:
http://notes_web:8080/ontraefik. - Builder accepts signed POST only; no GET health endpoint/Compose healthcheck. Do not expose it on Traefik for probing.
- Missing external network: fix Gitea's network creation first. Subnet collision: choose a free range, not deletion of unrelated networks.
- Accepted delivery without update: inspect clone/dependency/build/publication errors in builder logs.