forgerunner/docs/unraid.md

Unraid Deployment Guide

---

Overview

This guide covers deploying the custom-gitea-runner as a Docker container on an Unraid host. The recommended approach is Docker Compose via Unraid's compose manager, or manual template entry via the Unraid Docker UI.

---

Prerequisites

• Unraid with Docker enabled.
• Access to your Gitea instance admin panel to generate a runner token.
• The runner image pushed to your registry (e.g. registry.alwisp.com), or built locally on the Unraid host.

---

Step 1: Get a runner token

1. Log into your Gitea instance as an admin.
2. Go to Site Administration → Runners → Create new runner.
3. Copy the registration token. It will be used as GITEA_RUNNER_TOKEN.

---

Step 2: Set up appdata directories

mkdir -p /mnt/user/appdata/gitea-runner/config
mkdir -p /mnt/user/appdata/gitea-runner/work

If using custom CA certificates:

mkdir -p /mnt/user/appdata/gitea-runner/config/trusted-ca
# Copy your CA cert:
cp my-ca.crt /mnt/user/appdata/gitea-runner/config/trusted-ca/

---

Step 3: Docker UI container settings

In Unraid's Docker tab, click Add Container and fill in:

Basic

Field	Value
Name	gitea-runner
Repository	registry.alwisp.com/custom-gitea-runner:v0.1.0
Network Type	Bridge
Privileged	No
Restart	Unless Stopped

Environment variables

Key	Value
GITEA_INSTANCE_URL	https://git.example.com
GITEA_RUNNER_TOKEN	(your registration token)
GITEA_RUNNER_NAME	unraid-runner-01
GITEA_RUNNER_LABELS	ubuntu-latest:docker://node:20-bullseye
TZ	America/Chicago

Volumes

Container path	Host path	Mode
/config	/mnt/user/appdata/gitea-runner/config	Read/Write
/work	/mnt/user/appdata/gitea-runner/work	Read/Write
/var/run/docker.sock	/var/run/docker.sock	Read/Write

Click Apply.

---

Step 4: Verify startup

View container logs in the Unraid Docker UI or via terminal:

docker logs gitea-runner

First boot should show [BOOTSTRAP] Registration complete. Subsequent starts show [INFO] Existing config found.

---

Step 5: Verify in Gitea

Go to Gitea Site Administration → Runners. The runner should appear as Online.

---

Update procedure

1. Pull the new image tag to the Unraid host (or use the Community Applications plugin if listed).
2. In the Docker UI, edit the container and update the Repository to the new tag.
3. Click Apply — Unraid stops and recreates the container from the new image.
4. Check logs to confirm startup, then test a workflow.

Rollback procedure

Repeat the update procedure but specify the previous known-good tag.

---

Appdata backup

The /config volume (at /mnt/user/appdata/gitea-runner/config/) contains the runner registration config. Include it in Unraid's Appdata Backup plugin to preserve registration between host moves.

---

Notes

• The Docker socket mount (/var/run/docker.sock) is intentional and required for build/push workflows. On a single-tenant, self-owned Unraid host this is the standard approach.
• The /work directory grows as jobs run. You can safely clear it when no jobs are active to reclaim space.