[main]: add builder_notes docs

This commit is contained in:
John Gatward committed 2026-10-16 13:41:52 +01:00
1 parent 97f6dc28ae
commit 00ce362969
4 files changed
+123 -1

No files matched your search

+7 -1
View File
@@ -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
+2
View File
@@ -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 |
+113
View File
@@ -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.
+1
View File
@@ -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" },