ver 0.1

2026-06-29 21:56:12 -05:00
parent bc207c1cf7
commit 1757777a32
32 changed files with 1468 additions and 44 deletions
@@ -0,0 +1,121 @@
+# 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.