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,134 @@
+# Operations
+
+## Normal startup sequence
+
+When the container starts, expect to see:
+
+```
+======================================================
+  custom-gitea-runner
+  Image version : v0.1.0
+  Git revision  : abc1234
+======================================================
+Runtime:
+  act_runner : v0.2.11
+  node       : v20.x.x
+  npm        : 10.x.x
+  git        : 2.x.x
+  docker     : 24.x.x
+Config:
+  Config path  : /config/runner.yaml
+  Work dir     : /work
+  Gitea URL    : https://git.example.com
+  Runner name  : unraid-runner-01
+  Labels       : ubuntu-latest:docker://node:20-bullseye
+======================================================
+[OK] All required binaries present.
+[INFO] Existing config found at /config/runner.yaml. Skipping registration.
+[START] Starting act_runner daemon ...
+```
+
+On first boot with no config:
+
+```
+[BOOTSTRAP] No config found at /config/runner.yaml. Initiating registration.
+[BOOTSTRAP] Registration complete. Config at /config/runner.yaml.
+[START] Starting act_runner daemon ...
+```
+
+---
+
+## Health check
+
+The container runs a health check every 30s. Check status with:
+
+```bash
+docker inspect --format='{{.State.Health.Status}}' gitea-runner
+```
+
+Or view health check output:
+
+```bash
+docker inspect --format='{{json .State.Health}}' gitea-runner | jq .
+```
+
+Expected healthy output from `healthcheck.sh`:
+
+```
+[HEALTH] OK   : act_runner process is running
+[HEALTH] OK   : Config file present at /config/runner.yaml
+[HEALTH] OK   : Binary present: act_runner
+[HEALTH] OK   : Binary present: git
+[HEALTH] OK   : Binary present: node
+[HEALTH] OK   : Binary present: npm
+[HEALTH] OK   : Docker socket accessible
+```
+
+---
+
+## Smoke test
+
+Before production use, run the smoke test against the image:
+
+```bash
+./scripts/verify-runtime.sh custom-gitea-runner:v0.1.0
+```
+
+Or directly:
+
+```bash
+docker run --rm custom-gitea-runner:v0.1.0 /usr/local/bin/smoke-test.sh
+```
+
+---
+
+## Checking runner registration in Gitea
+
+1. Go to your Gitea instance.
+2. Navigate to **Site Administration → Runners** (admin panel) or **Repository Settings → Runners**.
+3. The runner should appear with status **Online**.
+
+---
+
+## Upgrade procedure
+
+1. Build or pull the new pinned image tag.
+2. Review `CHANGELOG.md` for breaking changes.
+3. Stop the existing container.
+4. Update the image tag in your compose file or Unraid template.
+5. Start the container.
+6. Verify startup logs and health check status.
+7. Run a smoke workflow to confirm job execution works.
+
+---
+
+## Rollback procedure
+
+1. Stop the container.
+2. Revert the image tag to the prior known-good version.
+3. Start the container.
+4. Confirm the registration config is still valid (it should be — it's persisted in the config volume).
+5. Run a smoke workflow.
+
+---
+
+## Re-registration
+
+If you need to re-register the runner (e.g. after a token reset or renaming):
+
+1. Stop the container.
+2. Delete `config/runner.yaml`.
+3. Set the new `GITEA_RUNNER_TOKEN` in your environment.
+4. Start the container — it will register fresh on boot.
+
+---
+
+## Log access
+
+```bash
+# Tail live logs
+docker logs -f gitea-runner
+
+# Last 100 lines
+docker logs --tail 100 gitea-runner
+```