114 lines
5.5 KiB
Markdown
114 lines
5.5 KiB
Markdown
---
|
|
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.
|