5.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 |
|
private-infrastructure | 2026-10-16 |
|
|
|
|
Notes
The repository configuration separates building the documentation from serving it. The current network configuration is intended state, not confirmation that the failed deployment has been recovered.
Services and build flow
| Component | Role |
|---|---|
notes_builder |
Zensical container running /builder/listener.py; receives signed Gitea webhooks on port 9000 and builds the main branch |
notes_web |
Unprivileged nginx serving the generated site on port 8080; Traefik publishes https://notes.umbra.mom behind Authentik forward-auth |
notes_static |
Shared named volume: builder writes /site-output; nginx mounts /usr/share/nginx/html read-only |
Gitea sends a push webhook to http://notes_builder:9000/. The listener checks
the X-Gitea-Signature HMAC against WEBHOOK_SECRET, queues accepted deliveries
and returns HTTP 202. A single worker clones
http://gitea:3000/jay/notes.git, then runs:
uv run --locked zensical build --clean --config-file zensical.toml
The repository must contain zensical.toml, pyproject.toml and uv.lock.
After a successful build with a generated index.html, the worker replaces the
contents of notes_static. Publication is not atomic: nginx can briefly see
missing files during replacement. HTTP 202 means queued, not build completed;
look for Documentation build succeeded in the builder logs.
Networks and webhook allowlist
| Setting | Repository configuration |
|---|---|
| Build network | notes_build, owned by the Gitea stack and external to the Notes stack |
| Subnet | 10.90.0.0/29 |
| Builder address | 10.90.0.3 |
| Gitea allowlist | GITEA__security__ALLOWED_HOST_LIST: "10.90.0.3:9000" |
| Web network | notes_web joins traefik; the builder does not |
Gitea 28 requires an explicit IP allow entry for a private destination.
notes_builder:9000 alone did not permit the resolved Docker IP. Keep the
network subnet, builder static IP and allowlist consistent; do not broadly allow
all private destinations.
The first proposed subnet, 172.30.90.0/29, overlapped an Actions network using
172.30.0.0/16. The replacement does not overlap the owner-supplied network
inventory or routes. Recheck for collisions before rebuilding on another host.
The build network is not internal: the builder needs outbound access to install
Git, uv and locked Python dependencies.
Deployment
Stack definitions follow the Portainer Git deployment workflow. Changing this documentation does not deploy either stack.
- Push the updated Compose definitions to
jupiter-stacks/main. Preserve the existing production environment settings in Portainer. - On Jupiter, ensure
/data/notes/listener.pyand/data/notes/nginx.confcontain the corresponding repository files. These are read-only bind mounts; pulling the stack repository does not populate or update them. - Set
WEBHOOK_SECRETin the Notes stack environment and the same secret in the Gitea Notes repository's push webhook. Keep the URLhttp://notes_builder:9000/; do not put the secret in Git or these notes. - Update/redeploy the Gitea stack first. It creates
notes_buildand applies the IP allow entry. Expect a brief Gitea interruption. - Confirm
docker network inspect notes_buildreports10.90.0.0/29, then update/redeploy the Notes stack. Avoid interrupting an active build. Preservenotes_static; do not remove volumes. - Wait for Gitea to be healthy and for
docker logs notes_builderto showListening on 9000. Redeliver the failed push webhook in Gitea. - Confirm HTTP
202, a successful build in the builder logs, and the updated page throughhttps://notes.umbra.momafter authentication.
Starting the builder alone does not trigger an initial build. If the static volume is empty, nginx cannot serve the site until an accepted webhook completes.
Health and troubleshooting
notes_web uses / on port 8080 for its container health check. For Homarr on
the shared traefik network, use http://notes_web:8080/.
The builder has no GET health endpoint or Compose health check; its listener
accepts signed POST requests only. Do not configure an ordinary HTTP GET ping
against http://notes_builder:9000/, or attach it to traefik just for a ping.
If Notes reports network notes_build declared as external, but could not be found, fix the Gitea network creation failure first. A subnet-overlap failure
requires an unused range, not deletion of unrelated Docker networks. If delivery
is accepted but the site does not update, inspect the builder logs for clone,
dependency installation, build or publication errors.