allucanget/calminer
2
0
Fork 0
Code Pull Requests Actions Packages Releases Activity
Files
29a17595daa8ec93f76642cebdbcee6cfc81f5bc
calminer/docs/architecture/07_deployment/07_03_gitea_action_runner.md

7.5 KiB
Raw Blame History

Gitea Action Runner Setup

This guide describes how to provision, configure, and maintain self-hosted runners for CalMiner's Gitea-based CI/CD pipelines.

1. Purpose and Scope

  • Explain the role runners play in executing GitHub Actions–compatible workflows inside our private Gitea instance.
  • Define supported environments (Windows hosts running Docker for Linux containers today, Alpine or other Linux variants as future additions).
  • Provide repeatable steps so additional runners can be brought online quickly and consistently.

2. Prerequisites

  • Hardware: Minimum 8 vCPU, 16 GB RAM, and 50 GB free disk. For Playwright-heavy suites, plan for ≥60 GB free to absorb browser caches.
  • Operating system: Current runner uses Windows 11 Pro (10.0.26100, 64-bit). Linux instructions mirror the same flow; see section 7 for Alpine specifics.
  • Container engine: Docker Desktop (Windows) or Docker Engine (Linux) with pull access to docker.gitea.com/runner-images and postgres:16-alpine.
  • Dependencies: curl, tar, PowerShell 7+ (Windows), or standard GNU utilities (Linux) to unpack releases.
  • Gitea access: Repository admin or site admin token with permission to register self-hosted runners (Settings → Runners → New Runner).

Current Runner Inventory (October 2025)

  • Hostname DESKTOP-GLB3A15; ASUS System Product Name chassis with AMD Ryzen 7 7700X (8C/16T) and ~63 GB usable RAM.
  • Windows 11 Pro 10.0.26100 (64-bit) hosting Docker containers for Ubuntu-based job images.
  • act_runner version v0.2.13; no act_runner.yaml present, so defaults apply (single concurrency, no custom labels beyond registration).
  • Registered against http://192.168.88.30:3000 with labels:
    • ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latest
    • ubuntu-24.04:docker://docker.gitea.com/runner-images:ubuntu-24.04
    • ubuntu-22.04:docker://docker.gitea.com/runner-images:ubuntu-22.04
  • Runner metadata stored in .runner; removing this file forces re-registration and should only be done intentionally.

3. Runner Installation

3.1 Download and Extract

$runnerVersion = "v0.2.13"
$downloadUrl = "https://gitea.com/gitea/act_runner/releases/download/$runnerVersion/act_runner_${runnerVersion}_windows_amd64.zip"
Invoke-WebRequest -Uri $downloadUrl -OutFile act_runner.zip
Expand-Archive act_runner.zip -DestinationPath C:\Tools\act-runner -Force

For Linux, download the linux_amd64.tar.gz artifact and extract with tar -xzf into /opt/act-runner.

3.2 Configure Working Directory

Set-Location C:\Tools\act-runner
New-Item -ItemType Directory -Path logs -Force | Out-Null

Ensure the directory is writable by the service account that will execute the runner.

3.3 Register With Gitea

  1. In Gitea, navigate to the repository or organization Settings → Runners → New Runner.
  2. Copy the registration token and instance URL.
  3. Execute the registration wizard:
.\act_runner.exe register --instance http://192.168.88.30:3000 --token <TOKEN> --labels "ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latest" "ubuntu-24.04:docker://docker.gitea.com/runner-images:ubuntu-24.04" "ubuntu-22.04:docker://docker.gitea.com/runner-images:ubuntu-22.04"

Linux syntax is identical using ./act_runner register.

This command populates .runner with the runner ID, UUID, and labels.

4. Service Configuration

4.1 Windows Service

Act Runner provides a built-in service helper:

.\act_runner.exe install
.\act_runner.exe start

The service runs under LocalSystem by default. Use .\act_runner.exe install --user <DOMAIN\User> --password <Secret> if isolation is required.

4.2 Linux systemd Unit

Create /etc/systemd/system/act-runner.service:

[Unit]
Description=Gitea Act Runner
After=docker.service
Requires=docker.service

[Service]
WorkingDirectory=/opt/act-runner
ExecStart=/opt/act-runner/act_runner daemon
Restart=always
RestartSec=10
Environment="HTTP_PROXY=http://apt-cacher:3142" "HTTPS_PROXY=http://apt-cacher:3142"

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable --now act-runner.service

4.3 Environment Variables and Proxy Settings

  • Configure HTTP_PROXY, HTTPS_PROXY, and their lowercase variants to leverage the shared apt cache (http://apt-cacher:3142).
  • Persist Docker registry credentials (for docker.gitea.com) in the service user profile using docker login; workflows rely on cached authentication for builds.
  • To expose pip caching once infrastructure is available, set PIP_INDEX_URL and PIP_EXTRA_INDEX_URL at the service level.

4.4 Logging

  • Windows services write to %ProgramData%\act-runner\logs. Redirect or forward to centralized logging if required.
  • Linux installations can leverage journalctl -u act-runner and logrotate rules for /opt/act-runner/logs.

5. Network and Security

  • Outbound: Allow HTTPS traffic to the Gitea instance, Docker Hub, docker.gitea.com, npm (for Playwright), PyPI, and the apt cache proxy.
  • Inbound: No inbound ports are required; block unsolicited traffic on internet-facing hosts.
  • Credentials: Store deployment SSH keys and registry credentials in Gitea secrets, not on the runner host.
  • Least privilege: Run the service under a dedicated account with access only to Docker and required directories.

6. Maintenance and Upgrades

  • Version checks: Monitor https://gitea.com/gitea/act_runner/releases and schedule upgrades quarterly or when security fixes drop.
  • Upgrade procedure: Stop the service, replace act_runner binary, restart. Re-registration is not required as long as .runner remains intact.
  • Health checks: Periodically validate connectivity with act_runner exec --detect-event -W .gitea/workflows/test.yml and inspect workflow durations to catch regressions.
  • Cleanup: Purge Docker images and volumes monthly (docker system prune -af) to reclaim disk space.
  • Troubleshooting: Use act_runner diagnose (if available in newer versions) or review logs for repeated failures; reset by stopping the service, deleting stale job containers (docker ps -a), and restarting.

7. Alpine-based Runner Notes

  • Install baseline packages: apk add docker bash curl coreutils nodejs npm python3 py3-pip libstdc++.
  • Playwright requirements: add apk add chromium nss freetype harfbuzz ca-certificates mesa-gl or install Playwright browsers via npx playwright install --with-deps using the Alpine bundle.
  • Musl vs glibc: When workflows require glibc (e.g., certain Python wheels), include apk add gcompat or base images on frolvlad/alpine-glibc.
  • Systemd alternative: Use rc-service or supervisord to manage act_runner daemon on Alpine since systemd is absent.
  • Storage: Mount /var/lib/docker to persistent storage if running inside a VM, ensuring browser downloads and layer caches survive restarts.

8. Appendix

  • Troubleshooting checklist:

    • Verify Docker daemon is healthy (docker info).
    • Confirm .runner file exists and lists expected labels.
    • Re-run act_runner register if the runner no longer appears in Gitea.
    • Check proxy endpoints are reachable before jobs start downloading dependencies.

  • Related documentation:

    • docs/architecture/07_deployment/07_01_testing_ci.md (workflow architecture and CI owner coordination).
    • docs/ci-cache-troubleshooting.md (pip caching status and known issues).
    • .gitea/actions/setup-python-env/action.yml (shared job preparation logic referenced in workflows).
View Git Blame Copy Permalink