# 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

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

If using custom CA certificates:

```bash
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:

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