publishing: build without credentials, publish from a host-owned script
Repo build logic now runs as the unprivileged docsbuild user with a scrubbed environment; the Cloudron token lives only in a root-owned publish script that executes no repository code.
This commit is contained in:
1 parent
f2e74564df
commit
b39c9b9289
2 files changed
+65
-91
No files matched your search
+42
-69
@@ -17,11 +17,11 @@ repository root.
|
||||
| `logo.svg` | Co-op logo (shared with the website repo) |
|
||||
| `build.sh` | Stage the Markdown into `.site-src/`, render to `.site-build/` |
|
||||
| `hooks.py` | MkDocs hooks: directory-link rewriting + content-hashed stylesheet URLs |
|
||||
| `deploy.sh` | Push the build into the Surfer app container |
|
||||
| `poll-watcher.sh` | Polls Gitea main every 60s; deploys on change (agent host) |
|
||||
| `docs-deploy-poll.service` | systemd unit for the poller |
|
||||
| `webhook-receiver.py` | Gitea webhook → pull → build → deploy (agent host) |
|
||||
| `webhook-receiver.service` | systemd unit for the receiver |
|
||||
| `deploy.sh` | Manual publish of the build into the Surfer app (needs a Cloudron token) |
|
||||
| `poll-watcher.sh` | Legacy poller; no longer installed — superseded by the host-owned poller |
|
||||
| `docs-deploy-poll.service` | systemd unit for the poller (runs the host-owned script) |
|
||||
| `webhook-receiver.py` | Webhook receiver; not installed (see below) |
|
||||
| `webhook-receiver.service` | systemd unit for the receiver; not installed |
|
||||
| `requirements.txt` | Pinned Python build toolchain |
|
||||
|
||||
Nothing external is loaded by the site: no CDN, no third-party font service.
|
||||
@@ -71,79 +71,52 @@ Override the destination with `SURFER_APP` (the app's Cloudron location) and
|
||||
|
||||
## Automatic rebuilds (push to main)
|
||||
|
||||
Two mechanisms keep the site in step with `main`; both run on the agent host
|
||||
and deploy into the docs Cloudron app above.
|
||||
`docs-deploy-poll.service` polls Gitea every 60 seconds and deploys whenever
|
||||
`main` moves, so a push appears on the site within about a minute with no human
|
||||
action. Edit, commit, push — that is the whole deployment story.
|
||||
|
||||
**Polling (running now).** `docs-deploy-poll.service` polls Gitea every 60
|
||||
seconds and deploys whenever `main` moves. A push appears on the site within
|
||||
about a minute, with no human action. The Gitea webhook alone was not enough
|
||||
because the agent host's cloud firewall only admits inbound SSH — a webhook
|
||||
POST is silently dropped — while outbound access to Gitea works.
|
||||
**The credential-bearing steps are host-owned, not repository code.** The
|
||||
poller runs a root-owned script (`/usr/local/sbin/docs-poll`) that does two
|
||||
separate jobs:
|
||||
|
||||
The service builds from a **dedicated clean clone** at
|
||||
`/home/ubuntu/.docs-publisher`, not from anyone's working copy, so uncommitted
|
||||
edits in a working clone can never block a deploy. Edit, commit, push — that
|
||||
is the whole deployment story.
|
||||
1. **Build as `docsbuild`.** The repository's build logic (`build.sh` → MkDocs
|
||||
→ `hooks.py`) runs as an unprivileged system user with a scrubbed
|
||||
environment, from its own clean clone at `/var/lib/docs-publisher/repo`
|
||||
with its own venv. That user cannot read `/home/ubuntu` (mode 750), so repo
|
||||
code cannot see any co-op credential — the Cloudron token, the gateway
|
||||
master key, the agent's env file.
|
||||
2. **Publish with a root-owned script.** `/usr/local/sbin/docs-publish` runs
|
||||
no repository code. It takes only the built directory, writes `meta.json`,
|
||||
and pushes it into the Surfer app using `CLOUDRON_TOKEN` from
|
||||
`/etc/docs-deploy.env` (root-only, mode 0600).
|
||||
|
||||
**Webhook (wired, waiting on one port).** A Gitea webhook is registered on
|
||||
`co-op/docs` (push events, branch `main`) pointing at the receiver below. The
|
||||
moment the Infomaniak panel allows inbound TCP to the agent host — port 8787
|
||||
from the Cloudron box 179.237.86.116 is enough — start the receiver and pushes
|
||||
deploy instantly instead of within a minute:
|
||||
A commit that lands on `main` therefore cannot execute anything with the
|
||||
Cloudron token. It can only influence the bytes of the site.
|
||||
|
||||
```sh
|
||||
sudo systemctl enable --now docs-deploy-webhook
|
||||
tail -f /home/ubuntu/docs-deploy.log # what both mechanisms are doing
|
||||
```
|
||||
|
||||
The receiver authenticates webhooks with an HMAC-SHA256 shared secret
|
||||
(`DEPLOY_WEBHOOK_SECRET` in the agent host's env file) and only accepts pushes
|
||||
to `main` of `co-op/docs` from the Cloudron box. Woodpecker CI (Cloudron
|
||||
catalog) could do the same job inside Cloudron, at the cost of running another
|
||||
app; the agent-host mechanisms were chosen because they add no new Cloudron app.
|
||||
**The webhook receiver is installed but not running.** `docs-deploy-webhook`
|
||||
is inactive and nothing listens on 8787. It predates this split, loads the
|
||||
agent's env file, and runs repo scripts with the Cloudron token; do not enable
|
||||
it without porting it to the same host-owned build/publish split. The Gitea
|
||||
webhook registration is harmless while the receiver is down.
|
||||
|
||||
Each deploy writes `meta.json` into the site with the commit it was built
|
||||
from, so a deploy can be verified from the served site itself:
|
||||
https://docs.inference.coop/meta.json
|
||||
|
||||
## One build environment (2026-11-12)
|
||||
If a deploy breaks, roll back with the saved unit
|
||||
(`/root/docs-deploy-poll.service.before-split`) and the previous build in
|
||||
`/var/lib/docs-publisher/repo/.site-build`; the poller retries every 60 seconds
|
||||
and sends one Matrix alert after 3 consecutive failures.
|
||||
|
||||
The deploy used to have TWO build environments — this repo's `.venv-docs` and
|
||||
a second private venv in the poller's checkout at
|
||||
`/home/ubuntu/.docs-publisher/.venv-docs`. They diverged twice, each time
|
||||
silently delaying a deploy (the brand.css cache-busting confusion, then a
|
||||
missing `mkdocs-redirects` that failed every build for ~15 minutes while the
|
||||
poller retried without telling anyone). Consolidated:
|
||||
## Build environment
|
||||
|
||||
- **ONE venv.** Every trigger — the poller, the (dormant) webhook receiver, a
|
||||
manual `publishing/build.sh`, CI — builds with the canonical checkout's
|
||||
venv: `~/repos/docs/.venv-docs`. The poller's private venv was deleted.
|
||||
- **The dedicated checkout stays, by design.** The poller still builds from
|
||||
`/home/ubuntu/.docs-publisher`, its own clean clone: uncommitted edits in a
|
||||
working clone must never block a deploy or leak into the published site.
|
||||
- **Drift check.** Before every build the poller compares `publishing/` and
|
||||
`mkdocs.yml` between its checkout and the canonical one; any mismatch fails
|
||||
the deploy loudly (with a diff and the fix — `git -C ~/repos/docs pull
|
||||
--ff-only`), and the failure counts toward the alert below. A canonical
|
||||
checkout that lags behind main trips this too, on purpose: a deploy of
|
||||
logic the canonical source cannot reproduce is the failure mode this exists
|
||||
to prevent. A missing canonical checkout is fatal as well.
|
||||
- **Plugin gate + self-heal.** `publishing/requirements.txt` pins every
|
||||
package the build needs (`mkdocs`, `mkdocs-material`, `mkdocs-redirects`).
|
||||
`build.sh` verifies the venv against it before every build and installs
|
||||
anything missing or off-version (fast local no-op when current); it also
|
||||
fails loudly if `mkdocs.yml` configures a plugin that `requirements.txt`
|
||||
does not pin. The poller runs this as its pre-deploy check via
|
||||
`build.sh --check-only`.
|
||||
- **Failure alerting.** After 3 consecutive deploy failures the poller writes
|
||||
a marker (`~/.docs-deploy.alert`) and sends ONE message to the InferenceBot
|
||||
HQ Matrix room naming the failing commit — never more than one message per
|
||||
hour (`~/.docs-deploy.last-alert`). The counter (`~/.docs-deploy.failcount`)
|
||||
resets on the next successful deploy. A deploy that succeeds silently
|
||||
resets everything; nothing announces routine successes.
|
||||
`publishing/requirements.txt` pins every package the build needs (`mkdocs`,
|
||||
`mkdocs-material`, `mkdocs-redirects`). `build.sh` verifies the build venv
|
||||
against it before every build and installs anything missing or off-version
|
||||
(fast local no-op when current); it also fails loudly if `mkdocs.yml`
|
||||
configures a plugin that `requirements.txt` does not pin.
|
||||
|
||||
Files: `~/.docs-deploy.state` (last deployed commit), `~/.docs-deploy.lock`
|
||||
(deploy lock), `~/.docs-deploy.failcount`, `~/.docs-deploy.alert`,
|
||||
`~/.docs-deploy.last-alert`. Manual deploys should respect the lock:
|
||||
`flock -n ~/.docs-deploy.lock bash publishing/build.sh && flock -n
|
||||
~/.docs-deploy.lock bash publishing/deploy.sh`.
|
||||
The deployed poller keeps one build venv at
|
||||
`/var/lib/docs-publisher/repo/.venv-docs`, owned by `docsbuild`. A manual
|
||||
`publishing/build.sh` uses `.venv-docs` in whatever checkout you run it from;
|
||||
that is fine for local previews and does not affect deploys.
|
||||
Reference in new issue
Block a user