# 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`.