--- schema_version: 1 id: home-server.notes type: reference scope: [jupiter, notes, gitea, webhooks, stack-deployment] sensitivity: private-infrastructure last_reviewed: "2026-10-16" 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: "Gitea private-address egress rejection, Docker network overlap failure, network inventory and host routes, 2026-10-16" related: [home-server.reference, home-server.deployment, home-server.networking, home-server.storage, home-server.authentication] update_triggers: [notes-stack-change, builder-change, webhook-change, network-change, deployment-workflow-change] unknowns: [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: ```sh 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](deployment.md). 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.