Jason Stedwell
1ad33c2396
- Publish v0.1.0/latest as multi-arch (linux/amd64+arm64); amd64 passes 17/17 smoke - publish-image.sh: add PLATFORMS multi-arch buildx mode (reproducible amd64 build) - compose + unraid notes: fix image path to include jason/ namespace - unraid notes: document required docker login (private package) and host label for docker build/push jobs Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
3.8 KiB
Unraid Template Notes — custom-gitea-runner
This document covers the recommended Unraid Docker container configuration for the custom-gitea-runner.
Container basics
| Field | Value |
|---|---|
| Repository | registry.alwisp.com/jason/custom-gitea-runner:v0.1.0 |
| Container name | gitea-runner |
| Network type | Bridge |
| Privileged | No (leave unchecked — socket mount handles Docker access) |
Registry authentication (required — image is private)
The image is published as a private package on the Gitea Container Registry, so the Unraid host must authenticate before it can pull it. Do this once via the Unraid terminal (or SSH):
docker login registry.alwisp.com -u <gitea-user>
# password: a Gitea access token with at least read:package scope
Credentials are stored in /root/.docker/config.json and persist across container recreations (but not necessarily across a full Unraid reboot if /root is on tmpfs — re-run if pulls start failing with unauthorized). Alternatively, make the package public in Gitea (Packages → custom-gitea-runner → Settings) to allow unauthenticated pulls.
Environment variables
Set these in the "Environment Variables" section of the Unraid container template.
| Variable | Required | Value |
|---|---|---|
GITEA_INSTANCE_URL |
Yes | https://git.example.com |
GITEA_RUNNER_TOKEN |
Yes | Registration token from Gitea admin |
GITEA_RUNNER_NAME |
Yes | e.g. unraid-runner-01 |
GITEA_RUNNER_LABELS |
No | ubuntu-latest:docker://node:20-bullseye,host:host |
RUNNER_CONFIG_PATH |
No | /config/runner.yaml |
RUNNER_WORKDIR |
No | /work |
TZ |
No | America/Chicago |
Volume mounts
| Container path | Host path | Notes |
|---|---|---|
/config |
/mnt/user/appdata/gitea-runner/config |
Config persistence. Generated on first boot. |
/work |
/mnt/user/appdata/gitea-runner/work |
Job workspace. Can be cleaned between runs. |
/var/run/docker.sock |
/var/run/docker.sock |
Docker socket. Required for build/push workflows. |
Post-install checklist
- Set all required environment variables.
- Start the container.
- Check logs — look for
[BOOTSTRAP] Registration completeor[START] Starting act_runner daemon. - In Gitea admin panel, verify the runner appears under Admin → Runners.
- Trigger a test workflow and confirm job pickup.
Update workflow
- Pull the new image tag from the registry.
- In Unraid, update the Repository field to the new pinned tag.
- Stop → Start the container (Unraid recreates from the new image).
- Confirm registration still valid in Gitea admin panel.
- Run a smoke workflow.
Rollback workflow
- Stop the container.
- Change the Repository field back to the prior known-good tag.
- Start the container.
- Verify registration and smoke workflow.
Notes on Docker socket
Mounting /var/run/docker.sock gives the runner access to the host Docker daemon. This is intentional for build/push workflows. Understand this means jobs running on this runner can interact with all containers on the Unraid host. For a self-owned, trusted environment this is acceptable. Future hardening options are documented in docs/architecture.md.
Labels: which to use for Docker build/push
docker build/docker push steps need the bundled Docker CLI and the mounted socket, which only exist in the runner container itself — not inside the ubuntu-latest job container (a plain node image). Run Docker-centric jobs with runs-on: host. Use ubuntu-latest:docker://… for jobs that should run in a clean throwaway container. Registering with both labels (ubuntu-latest:…,host:host) covers both patterns. This was validated end-to-end against git.alwisp.com (see forgerunner.src/ROADMAP.md Phase 3).