[main]: add builder_notes docs
This commit is contained in:
4 files changed
+123
-1
No files matched your search
@@ -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
|
||||
|
||||
@@ -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 |
|
||||
|
||||
@@ -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.
|
||||
Reference in new issue
Block a user