From c414984ba37244fb38e286f886fccec5f77e0d4f Mon Sep 17 00:00:00 2001
From: paste <paste2950@gmail.com>
Date: Thu, 25 Jun 2026 22:16:17 -0500
Subject: [PATCH] Add act_runner setup (Docker Compose) for octowow.st

---
 .gitignore                |  3 ++
 runner/.env.example       |  5 +++
 runner/README.md          | 68 +++++++++++++++++++++++++++++++++++++++
 runner/docker-compose.yml | 26 +++++++++++++++
 4 files changed, 102 insertions(+)
 create mode 100644 runner/.env.example
 create mode 100644 runner/README.md
 create mode 100644 runner/docker-compose.yml

diff --git a/.gitignore b/.gitignore
index 8923179..b95a25f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -5,3 +5,6 @@ test/dist/
 # local validation helpers (not needed in CI)
 test/stub_mpqpack.py
 test/mpqpack.cmd
+# runner secrets/state
+runner/.env
+runner/data/
diff --git a/runner/.env.example b/runner/.env.example
new file mode 100644
index 0000000..9a7ba5a
--- /dev/null
+++ b/runner/.env.example
@@ -0,0 +1,5 @@
+# Copy to `.env` (same folder) and fill in. Do NOT commit .env — it holds the token.
+# Get the token at: https://octowow.st/git/user/settings/actions/runners
+#   -> "Create new Runner" -> copy the registration token.
+RUNNER_TOKEN=paste-registration-token-here
+RUNNER_NAME=octo-windows-runner
diff --git a/runner/README.md b/runner/README.md
new file mode 100644
index 0000000..d7b4e14
--- /dev/null
+++ b/runner/README.md
@@ -0,0 +1,68 @@
+# act_runner setup (octowow.st)
+
+Stands up a self-hosted Gitea Actions runner as a container. One runner
+registered at the **user level** serves all of your repos (`GlueXML`,
+`mpq-packager`, …).
+
+## Prerequisites on the runner host
+
+- **Docker** running. On Windows/macOS that means Docker Desktop with the Linux
+  engine (WSL2 backend on Windows). Settings → Advanced → keep "Allow the
+  default Docker socket to be used" enabled so the socket mount works.
+
+## 1. Get a registration token
+
+In the Gitea web UI, as your user:
+
+> avatar → **Settings** → **Actions** → **Runners** → **Create new Runner**
+
+Copy the **registration token** (a long string). This is user-scoped, so the
+runner picks up jobs from any of your repos.
+
+Direct link: <https://octowow.st/git/user/settings/actions/runners>
+
+> A repo-scoped token (repo → Settings → Actions → Runners) also works if you
+> only want the runner tied to one repo.
+
+## 2. Configure
+
+```sh
+cp .env.example .env
+# edit .env: paste RUNNER_TOKEN, set RUNNER_NAME
+```
+
+## 3. Start
+
+```sh
+docker compose up -d
+docker compose logs -f        # watch it register
+```
+
+The runner should appear as **Idle / online** in the Runners list within a few
+seconds.
+
+## 4. Enable Actions on each repo
+
+Per repo: **Settings → Actions →** enable. New repos have it off by default.
+
+## 5. Verify
+
+Push a tag (or run a workflow) and watch it execute under the **Actions** tab.
+For `mpq-packager`'s release flow, a `v*` tag on a consuming repo builds the MPQ
+and attaches it to a release.
+
+## Notes
+
+- **First job is slow** — it pulls `catthehacker/ubuntu:act-latest` (~1 GB) the
+  first time; cached afterward.
+- **`runs-on` labels** must match `GITEA_RUNNER_LABELS`. We map
+  `ubuntu-latest` → `catthehacker/ubuntu:act-latest`. Add more pairs
+  (comma-separated) to support other labels.
+- **Docker actions** (e.g. `uses: paste/mpq-packager@v1`) work out of the box:
+  act_runner builds and runs them via the mounted host socket.
+- **Workflows that run `docker` CLI in a step** (like this repo's own
+  `.gitea/workflows/ci.yml`) need the job container to reach Docker too. The
+  release workflow does not — it only *uses* the Docker action — so it's fine.
+  Ask if you want the CI's docker-in-job case wired up.
+- **Re-registering**: delete `./data` and `docker compose up -d` again with a
+  fresh token.
diff --git a/runner/docker-compose.yml b/runner/docker-compose.yml
new file mode 100644
index 0000000..9faa4dd
--- /dev/null
+++ b/runner/docker-compose.yml
@@ -0,0 +1,26 @@
+# act_runner for octowow.st, run as a container (Docker Compose).
+# Copy this folder to the runner host, fill in .env (see .env.example),
+# then: docker compose up -d
+#
+# The runner auto-registers on first start using the env vars below, then
+# persists its credentials in ./data so restarts don't re-register.
+
+services:
+  act_runner:
+    image: gitea/act_runner:latest
+    container_name: octo-act-runner
+    restart: always
+    environment:
+      # Gitea base URL — note the /git path on this instance.
+      GITEA_INSTANCE_URL: https://octowow.st/git
+      # Registration token from Settings -> Actions -> Runners -> "Create new Runner".
+      GITEA_RUNNER_REGISTRATION_TOKEN: ${RUNNER_TOKEN}
+      GITEA_RUNNER_NAME: ${RUNNER_NAME:-octo-runner}
+      # runs-on label -> image mapping. ubuntu-latest uses the de-facto act image.
+      GITEA_RUNNER_LABELS: ubuntu-latest:docker://catthehacker/ubuntu:act-latest
+    volumes:
+      # Host Docker socket: act_runner spawns job/action containers as siblings.
+      # On Docker Desktop (Windows/Mac) this path is provided by the Linux engine.
+      - /var/run/docker.sock:/var/run/docker.sock
+      # Persist runner registration + state.
+      - ./data:/data