[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/gitea/docker-compose.yml
|
||||||
- stacks/immich/docker-compose.yml
|
- stacks/immich/docker-compose.yml
|
||||||
- stacks/paperless-ngx/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]
|
update_triggers: [deployment-workflow-change, repository-change, credential-rotation, rollback-policy-change]
|
||||||
unknowns:
|
unknowns:
|
||||||
- github-pat-scopes-and-expiration
|
- 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
|
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.
|
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
|
## Authentik configuration surfaces
|
||||||
|
|
||||||
The owner reports the Authelia-to-Authentik migration complete. Rebuilding it
|
The owner reports the Authelia-to-Authentik migration complete. Rebuilding it
|
||||||
|
|||||||
@@ -16,6 +16,7 @@ related:
|
|||||||
- home-server.seedbox
|
- home-server.seedbox
|
||||||
- home-server.portainer
|
- home-server.portainer
|
||||||
- home-server.deployment
|
- home-server.deployment
|
||||||
|
- home-server.notes
|
||||||
- home-server.operations
|
- home-server.operations
|
||||||
- home-server.networking
|
- home-server.networking
|
||||||
- home-server.storage
|
- home-server.storage
|
||||||
@@ -34,6 +35,7 @@ unknowns: []
|
|||||||
| [Seedbox](seedbox.md) | Ultra.cc; qBittorrent; rclone mount |
|
| [Seedbox](seedbox.md) | Ultra.cc; qBittorrent; rclone mount |
|
||||||
| [Portainer](portainer.md) | Script-managed container; state; backups |
|
| [Portainer](portainer.md) | Script-managed container; state; backups |
|
||||||
| [Deployment](deployment.md) | GitHub; Portainer; environment values |
|
| [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 |
|
| [Operations / decisions](operations.md) | Tradeoffs; monitoring; recovery gaps |
|
||||||
| [Networking](networking.md) | Mercury; WireGuard; DNS; ingress |
|
| [Networking](networking.md) | Mercury; WireGuard; DNS; ingress |
|
||||||
| [Storage](storage.md) | SSD; RAID 0; mounts; volumes |
|
| [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.
|
||||||
@@ -17,6 +17,7 @@ nav = [
|
|||||||
{ "Seedbox" = "home-server/seedbox.md" },
|
{ "Seedbox" = "home-server/seedbox.md" },
|
||||||
{ "Portainer" = "home-server/portainer.md" },
|
{ "Portainer" = "home-server/portainer.md" },
|
||||||
{ "Deployment" = "home-server/deployment.md" },
|
{ "Deployment" = "home-server/deployment.md" },
|
||||||
|
{ "Notes" = "home-server/notes.md" },
|
||||||
{ "Operations / decisions" = "home-server/operations.md" },
|
{ "Operations / decisions" = "home-server/operations.md" },
|
||||||
{ "Networking" = "home-server/networking.md" },
|
{ "Networking" = "home-server/networking.md" },
|
||||||
{ "Storage" = "home-server/storage.md" },
|
{ "Storage" = "home-server/storage.md" },
|
||||||
|
|||||||
Reference in new issue
Block a user