--- schema_version: 1 id: home-server.notes type: reference scope: [jupiter, notes, gitea, webhooks] sensitivity: private-infrastructure last_reviewed: "2026-10-27" sources: - kind: repository repository: jupiter-stacks revision: f39d0f4028f9fe70f838a0ec577d10ab11409f5c paths: [stacks/gitea/docker-compose.yml, stacks/notes/docker-compose.yml, stacks/notes/listener.py, stacks/notes/nginx.conf] - kind: owner-report reference: "Private-address webhook rejection, subnet overlap and host/network inventory, 2026-10-16" related: [home-server.deployment, home-server.networking, home-server.storage, home-server.authentication] update_triggers: [builder-change, webhook-change, network-change] unknowns: [successful-notes-build-network-deployment, successful-webhook-redelivery] --- # Notes publication Repository intent; recovery from the previously failed deployment is unconfirmed. ```mermaid --- 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
main"]:::infraClient Builder["notes_builder :9000
HMAC check / queue / build"]:::infraEdge Static[("notes_static
generated site")]:::infraStorage Web["notes_web :8080
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](authentication.md#forward-auth). - Clone source: `http://gitea:3000/jay/notes.git`; requires `zensical.toml`, `pyproject.toml`, `uv.lock`. - Listener `/builder/listener.py` checks `X-Gitea-Signature` with `WEBHOOK_SECRET`. - **202 = queued**, not built. Single worker logs `Documentation build succeeded` after generated `index.html`. - Publication replaces volume contents non-atomically; brief missing files possible. Starting an empty builder does not trigger a build. ```sh 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/29` overlapped Actions' `172.30.0.0/16`. - Build network is non-internal: dependency installation requires outbound access. ## Deployment 1. Push stack changes; preserve Portainer values. Copy listener/nginx config into `/data/notes/{listener.py,nginx.conf}`; Git pull does not update binds. 2. Set matching `WEBHOOK_SECRET` in Notes and Gitea's push webhook; retain the internal webhook URL. 3. Redeploy **Gitea first**; confirm `notes_build` has the expected subnet/allowlist. 4. Redeploy Notes outside an active build; preserve `notes_static`, never remove volumes. 5. Wait for healthy Gitea and builder `Listening on 9000`; redeliver the webhook. 6. Confirm 202, build-success log and authenticated updated page. ## Health / troubleshooting - Web probe: `http://notes_web:8080/` on `traefik`. - 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.