85 lines
4.4 KiB
Markdown
85 lines
4.4 KiB
Markdown
---
|
|
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<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](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.
|