diff --git a/docs/home-server/deployment.md b/docs/home-server/deployment.md index e6362b6..656a53b 100644 --- a/docs/home-server/deployment.md +++ b/docs/home-server/deployment.md @@ -23,7 +23,7 @@ sources: - stacks/gitea/docker-compose.yml - stacks/immich/docker-compose.yml - stacks/paperless-ngx/docker-compose.yml -related: [home-server.reference, home-server.host, home-server.portainer, home-server.authentication, home-server.backups, home-server.operations] +related: [home-server.reference, home-server.host, home-server.portainer, home-server.authentication, home-server.backups, home-server.operations, home-server.notes] update_triggers: [deployment-workflow-change, repository-change, credential-rotation, rollback-policy-change] unknowns: - github-pat-scopes-and-expiration @@ -57,6 +57,12 @@ No independent recovery arrangement exists for the PAT or stack secrets. Rollback, health-check gates, approval rules and UI-versus-Git drift policy are not established; do not assume permission to deploy, stop or delete services. +## Notes deployment + +The [Notes reference](notes.md) covers `notes_builder`, `notes_web`, host bind +mounts, the signed Gitea webhook and the shared static volume. Deploy Gitea before +Notes: Gitea owns the `notes_build` network that the Notes stack consumes. + ## Authentik configuration surfaces The owner reports the Authelia-to-Authentik migration complete. Rebuilding it diff --git a/docs/home-server/index.md b/docs/home-server/index.md index d8de79b..267a8df 100644 --- a/docs/home-server/index.md +++ b/docs/home-server/index.md @@ -16,6 +16,7 @@ related: - home-server.seedbox - home-server.portainer - home-server.deployment + - home-server.notes - home-server.operations - home-server.networking - home-server.storage @@ -34,6 +35,7 @@ unknowns: [] | [Seedbox](seedbox.md) | Ultra.cc; qBittorrent; rclone mount | | [Portainer](portainer.md) | Script-managed container; state; backups | | [Deployment](deployment.md) | GitHub; Portainer; environment values | +| [Notes](notes.md) | Webhook builder; static site; networks; deployment order | | [Operations / decisions](operations.md) | Tradeoffs; monitoring; recovery gaps | | [Networking](networking.md) | Mercury; WireGuard; DNS; ingress | | [Storage](storage.md) | SSD; RAID 0; mounts; volumes | diff --git a/docs/home-server/notes.md b/docs/home-server/notes.md new file mode 100644 index 0000000..353b761 --- /dev/null +++ b/docs/home-server/notes.md @@ -0,0 +1,113 @@ +--- +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. diff --git a/zensical.toml b/zensical.toml index 0628f3b..f502083 100644 --- a/zensical.toml +++ b/zensical.toml @@ -17,6 +17,7 @@ nav = [ { "Seedbox" = "home-server/seedbox.md" }, { "Portainer" = "home-server/portainer.md" }, { "Deployment" = "home-server/deployment.md" }, + { "Notes" = "home-server/notes.md" }, { "Operations / decisions" = "home-server/operations.md" }, { "Networking" = "home-server/networking.md" }, { "Storage" = "home-server/storage.md" },