Files
notes/docs/home-server/notes.md
T
2026-10-29 15:28:47 +00:00

4.5 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
jupiter
notes
gitea
webhooks
private-infrastructure 2026-10-27
kind repository revision paths
repository jupiter-stacks f39d0f4028f9fe70f838a0ec577d10ab11409f5c
stacks/gitea/docker-compose.yml
stacks/notes/docker-compose.yml
stacks/notes/listener.py
stacks/notes/nginx.conf
kind reference
owner-report Private-address webhook rejection, subnet overlap and host/network inventory, 2026-10-16
home-server.deployment
home-server.networking
home-server.storage
home-server.authentication
builder-change
webhook-change
network-change
successful-notes-build-network-deployment
successful-webhook-redelivery

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://docs.umbra.mom, Traefik + Authentik forward-auth.
  • https://notes.umbra.mom is reserved for Joplin Server sync, using native Authentik SAML and the Joplin Server (SAML) client target.
  • 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.
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.