Files
notes/docs/home-server/notes.md
T

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
jupiter
notes
gitea
webhooks
stack-deployment
private-infrastructure 2026-10-16
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 Gitea private-address egress rejection, Docker network overlap failure, network inventory and host routes, 2026-10-16
home-server.reference
home-server.deployment
home-server.networking
home-server.storage
home-server.authentication
notes-stack-change
builder-change
webhook-change
network-change
deployment-workflow-change
successful-deployment-of-notes-build-network
successful-webhook-redelivery

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.

  1. Push the updated Compose definitions to jupiter-stacks/main. Preserve the existing production environment settings in Portainer.
  2. On Jupiter, ensure /data/notes/listener.py and /data/notes/nginx.conf contain the corresponding repository files. These are read-only bind mounts; pulling the stack repository does not populate or update them.
  3. Set WEBHOOK_SECRET in the Notes stack environment and the same secret in the Gitea Notes repository's push webhook. Keep the URL http://notes_builder:9000/; do not put the secret in Git or these notes.
  4. Update/redeploy the Gitea stack first. It creates notes_build and applies the IP allow entry. Expect a brief Gitea interruption.
  5. Confirm docker network inspect notes_build reports 10.90.0.0/29, then update/redeploy the Notes stack. Avoid interrupting an active build. Preserve notes_static; do not remove volumes.
  6. Wait for Gitea to be healthy and for docker logs notes_builder to show Listening on 9000. Redeliver the failed push webhook in Gitea.
  7. Confirm HTTP 202, a successful build in the builder logs, and the updated page through https://notes.umbra.mom after 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.