Jason Stedwell
1ad33c2396
CI Smoke / toolchain (push) Successful in 1s
- Publish v0.1.0/latest as multi-arch (linux/amd64+arm64); amd64 passes 17/17 smoke - publish-image.sh: add PLATFORMS multi-arch buildx mode (reproducible amd64 build) - compose + unraid notes: fix image path to include jason/ namespace - unraid notes: document required docker login (private package) and host label for docker build/push jobs Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
93 lines
3.8 KiB
Markdown
93 lines
3.8 KiB
Markdown
# 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/jason/custom-gitea-runner:v0.1.0` |
|
|
| Container name | `gitea-runner` |
|
|
| Network type | `Bridge` |
|
|
| Privileged | `No` (leave unchecked — socket mount handles Docker access) |
|
|
|
|
---
|
|
|
|
## Registry authentication (required — image is private)
|
|
|
|
The image is published as a **private** package on the Gitea Container Registry, so the Unraid host must authenticate before it can pull it. Do this once via the Unraid terminal (or SSH):
|
|
|
|
```bash
|
|
docker login registry.alwisp.com -u <gitea-user>
|
|
# password: a Gitea access token with at least read:package scope
|
|
```
|
|
|
|
Credentials are stored in `/root/.docker/config.json` and persist across container recreations (but not necessarily across a full Unraid reboot if `/root` is on tmpfs — re-run if pulls start failing with `unauthorized`). Alternatively, make the package public in Gitea (Packages → custom-gitea-runner → Settings) to allow unauthenticated pulls.
|
|
|
|
---
|
|
|
|
## 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,host:host` |
|
|
| `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`.
|
|
|
|
## Labels: which to use for Docker build/push
|
|
|
|
`docker build`/`docker push` steps need the bundled Docker CLI and the mounted socket, which only exist in the runner container itself — not inside the `ubuntu-latest` job container (a plain `node` image). Run Docker-centric jobs with `runs-on: host`. Use `ubuntu-latest:docker://…` for jobs that should run in a clean throwaway container. Registering with both labels (`ubuntu-latest:…,host:host`) covers both patterns. This was validated end-to-end against `git.alwisp.com` (see `forgerunner.src/ROADMAP.md` Phase 3).
|