Jason Stedwell
2.5 KiB
2.5 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/custom-gitea-runner:v0.1.0 |
| Container name | gitea-runner |
| Network type | Bridge |
| Privileged | No (leave unchecked — socket mount handles Docker access) |
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 |
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.