---
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.