76 lines
2.5 KiB
Markdown
76 lines
2.5 KiB
Markdown
|
# 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
|
||
|
|
|
||
|
|
1. Set all required environment variables.
|
||
|
|
2. Start the container.
|
||
|
|
3. Check logs — look for `[BOOTSTRAP] Registration complete` or `[START] Starting act_runner daemon`.
|
||
|
|
4. In Gitea admin panel, verify the runner appears under **Admin → Runners**.
|
||
|
|
5. Trigger a test workflow and confirm job pickup.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Update workflow
|
||
|
|
|
||
|
|
1. Pull the new image tag from the registry.
|
||
|
|
2. In Unraid, update the Repository field to the new pinned tag.
|
||
|
|
3. Stop → Start the container (Unraid recreates from the new image).
|
||
|
|
4. Confirm registration still valid in Gitea admin panel.
|
||
|
|
5. Run a smoke workflow.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Rollback workflow
|
||
|
|
|
||
|
|
1. Stop the container.
|
||
|
|
2. Change the Repository field back to the prior known-good tag.
|
||
|
|
3. Start the container.
|
||
|
|
4. 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`.
|