From d4f180d57fe2d34ed218221995c3785211bcc4f3 Mon Sep 17 00:00:00 2001
From: Vuong Hoang <vh@phasefinal.com>
Date: Wed, 3 Jun 2026 01:25:20 -0700
Subject: [PATCH] =?UTF-8?q?docs(runbook):=20yt-voice-clipper=20push-to-dep?=
 =?UTF-8?q?loy=20(gitea=20webhook=20=E2=86=92=20irv-ml1)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Auto-deploy on push to main: gitea webhook → HMAC-validated listener on irv-ml1:9008
→ git fetch/reset + docker compose up -d --build. Documents the gitea-server
ALLOWED_HOST_LIST anti-SSRF relaxation (scoped to the WG net), the irv-ml1 components
(deploy key, git-clone deploy dir preserving the proxy override/secrets, listener +
user service), and verify/debug steps.
---
 docs/runbooks/ytvc-autodeploy.md | 56 ++++++++++++++++++++++++++++++++
 1 file changed, 56 insertions(+)
 create mode 100644 docs/runbooks/ytvc-autodeploy.md

diff --git a/docs/runbooks/ytvc-autodeploy.md b/docs/runbooks/ytvc-autodeploy.md
new file mode 100644
index 0000000..2e62002
--- /dev/null
+++ b/docs/runbooks/ytvc-autodeploy.md
@@ -0,0 +1,56 @@
+# yt-voice-clipper push-to-deploy (gitea webhook → irv-ml1)
+
+Auto-deploys `vh/yt-voice-clipper` to irv-ml1 on every push to `main`. Built
+2026-06-03 to end a run of manual rebuilds (the tool's frontend iterates fast).
+
+## Flow
+
+```
+push to main → gitea webhook (POST) → HMAC-validated listener on irv-ml1:9008
+            → ~/ytvc-deploy.sh : git fetch + reset --hard origin/main + docker compose up -d --build
+```
+
+main-only (other branches ignored). The deploy log is `~/.config/ytvc/deploy.log`
+on irv-ml1.
+
+## Components
+
+**On the gitea server** (container `gitea` on **ana-docker**, data volume
+`gitea_gitea_data`, app.ini at `/data/gitea/conf/app.ini`):
+- `[webhook] ALLOWED_HOST_LIST = external, 10.100.0.0/16` — relaxes gitea's
+  anti-SSRF guard to allow webhooks to the WG net (irv-ml1 is a private WG IP;
+  the default `external` denies it). **Keep it scoped** — never `*`/`private`.
+  Backup at `app.ini.bak-pre-webhook`. Requires `docker restart gitea` to apply
+  (act_runner job containers survive the restart).
+- Webhook on the repo: Target `http://10.100.79.3:9008/`, content-type
+  `application/json`, Push events only, the shared secret.
+
+**On irv-ml1** (all under `lkraven`, no root needed except the one-time
+`loginctl enable-linger lkraven`):
+- Deploy dir `/opt/docker/compose/yt-voice-clipper` is a **git clone**
+  (remote `git@gitea-ytvc:vh/yt-voice-clipper.git` via read-only deploy key
+  `~/.ssh/gitea_ytvc_deploy` + ssh-config `Host gitea-ytvc`). `.env`,
+  `secrets/`, `docker-compose.override.yml` stay UNTRACKED so `git reset --hard`
+  preserves them (incl. the `YTVC_PROXY` egress-proxy override).
+- `~/ytvc-deploy.sh` — the deploy (fetch + reset + rebuild + recreate).
+- `~/ytvc-webhook.py` — listener on `:9008`, HMAC-SHA256 validates
+  `X-Gitea-Signature` against `~/.config/ytvc/webhook-secret` (mode 600), fires
+  the deploy only on a verified push to `refs/heads/main`.
+- `systemctl --user` service `ytvc-webhook.service` (lingering enabled).
+
+## Verify / debug
+
+```bash
+# listener up?
+ssh irv-ml1 'curl -s localhost:9008/'                       # -> ytvc-webhook ok
+ssh irv-ml1 'systemctl --user is-active ytvc-webhook'
+# deploys
+ssh irv-ml1 'tail -20 ~/.config/ytvc/deploy.log'
+# manual deploy (same as the webhook does)
+ssh irv-ml1 'bash ~/ytvc-deploy.sh'
+# gitea side: repo → Settings → Webhooks → Test Delivery (expect 202)
+```
+
+If gitea Test Delivery shows `dial tcp ... webhook can only call allowed HTTP
+servers` → the `ALLOWED_HOST_LIST` change above is missing or gitea wasn't
+restarted.