Jason Stedwell
122 lines
3.2 KiB
Markdown
122 lines
3.2 KiB
Markdown
# 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.
|