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,48 @@
+# docker-compose.example.yml — custom-gitea-runner deployment
+# Copy and adjust for your environment. Use pinned image tags in production.
+#
+# Modes:
+#   Mode A (pre-generated config): mount config/runner.yaml — set RUNNER_CONFIG_PATH
+#   Mode B (bootstrap on first run): set GITEA_INSTANCE_URL, GITEA_RUNNER_TOKEN, GITEA_RUNNER_NAME
+
+services:
+  gitea-runner:
+    image: registry.alwisp.com/custom-gitea-runner:v0.1.0  # pin your version here
+    container_name: gitea-runner
+    restart: unless-stopped
+
+    environment:
+      # ── Required for Mode B (bootstrap registration) ───────────────────────
+      GITEA_INSTANCE_URL: https://git.example.com
+      GITEA_RUNNER_NAME: unraid-runner-01
+      GITEA_RUNNER_TOKEN: ${GITEA_RUNNER_TOKEN}      # set in .env file
+
+      # ── Optional ──────────────────────────────────────────────────────────
+      GITEA_RUNNER_LABELS: ubuntu-latest:docker://node:20-bullseye
+      RUNNER_CONFIG_PATH: /config/runner.yaml
+      RUNNER_WORKDIR: /work
+      TZ: America/Chicago
+
+    volumes:
+      # Runner config (persisted across restarts; generated on first boot in Mode B)
+      - ./config:/config
+
+      # Job workspace (writable scratch space for running jobs)
+      - ./work:/work
+
+      # Docker socket — required for docker build/push workflows
+      # Grants the runner full Docker daemon access. Understand the trust model.
+      - /var/run/docker.sock:/var/run/docker.sock
+
+    # Limit resources to avoid runaway jobs starving the host
+    deploy:
+      resources:
+        limits:
+          cpus: "4"
+          memory: 4G
+
+    logging:
+      driver: json-file
+      options:
+        max-size: "10m"
+        max-file: "3"
@@ -0,0 +1,75 @@
+# 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/custom-gitea-runner:v0.1.0` |
+| Container name | `gitea-runner` |
+| Network type | `Bridge` |
+| Privileged | `No` (leave unchecked — socket mount handles Docker access) |
+
+---
+
+## 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` |
+| `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`.