docs: add runner setup guide and align workflow label

2026-05-07 22:13:51 +00:00
parent 257889f1e2
commit 76402492c2
2 changed files with 120 additions and 3 deletions
@@ -0,0 +1,119 @@
+# Gitea Actions runner setup for this repo
+
+This repository expects a Gitea Actions runner with the label:
+
+- `alpine-latest:docker://node:20-alpine`
+
+That label is intentional:
+- `actions/checkout@v4` needs a Node-capable job image
+- the build itself wants `apk`, which is easiest on Alpine
+- the workflow then compiles a static `musl` binary directly inside the job container
+
+## Recommended placement in your infra
+
+Best fit: **your NL dedicated Debian 12 server**.
+
+Why:
+- separate from the Gitea host, which is the recommended topology
+- always-on box
+- Docker is straightforward there
+- enough resources for lightweight source builds
+
+Home server also works, but the NL dedicated host is the cleaner default.
+
+## 1. Confirm Actions are enabled in Gitea
+
+Your Gitea is `1.26.1`, so instance-level Actions support is already built in by default.
+
+Still verify:
+- repo: `xnullzz/static-musl-builds`
+- open `Settings -> Actions`
+- ensure **Enable Repository Actions** is on
+
+The workflow is already detected by Gitea, so the remaining missing piece is the runner.
+
+## 2. Get a registration token
+
+You can create either:
+- an **instance runner** token in `Site Administration -> Actions -> Runners`, or
+- a **repository runner** token in `xnullzz/static-musl-builds -> Settings -> Actions -> Runners`
+
+For this project, a repository runner is enough.
+
+## 3. Install Docker on the runner host
+
+On Debian 12:
+
+```bash
+sudo apt-get update
+sudo apt-get install -y ca-certificates curl docker.io
+sudo systemctl enable --now docker
+```
+
+## 4. Run act_runner in Docker
+
+Create a directory:
+
+```bash
+sudo mkdir -p /opt/gitea-runner
+sudo chown "$USER":"$USER" /opt/gitea-runner
+cd /opt/gitea-runner
+```
+
+Create `docker-compose.yml`:
+
+```yaml
+services:
+  runner:
+    image: docker.io/gitea/act_runner:0.2.11
+    restart: always
+    environment:
+      CONFIG_FILE: /config.yaml
+      GITEA_INSTANCE_URL: "https://g.o4kosebezablokiruyte.ru"
+      GITEA_RUNNER_REGISTRATION_TOKEN: "PUT_TOKEN_HERE"
+      GITEA_RUNNER_NAME: "nl-dedicated-static-builder"
+      GITEA_RUNNER_LABELS: "alpine-latest:docker://node:20-alpine,ubuntu-latest:docker://node:20-bookworm"
+    volumes:
+      - ./config.yaml:/config.yaml
+      - ./data:/data
+      - /var/run/docker.sock:/var/run/docker.sock
+```
+
+Generate a starter config:
+
+```bash
+docker run --rm --entrypoint="" docker.io/gitea/act_runner:0.2.11 \
+  act_runner generate-config > config.yaml
+mkdir -p data
+```
+
+Then start it:
+
+```bash
+docker compose up -d
+```
+
+## 5. Verify the runner
+
+In Gitea, confirm the runner appears as online.
+
+You should see labels including:
+- `alpine-latest`
+- `ubuntu-latest`
+
+## 6. Trigger a test build
+
+After the runner is online, either:
+- re-run the queued workflow from the Actions UI, or
+- push any small commit to `main`
+
+Expected result:
+- workflow builds `iperf3`
+- a release tagged like `iperf3-v3.21` appears
+- release assets include the static binary, tarball, and sha256 file
+
+## Notes
+
+- The queued run already visible in Gitea means repo Actions are working; only execution capacity is missing.
+- If you later add more binaries, the same runner can be reused.
+- If you want stricter isolation later, you can move to ephemeral runners, but for a personal infra repo this persistent Docker runner is a good starting point.