# 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

```powershell
$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

```powershell
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:

```powershell
.\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:

```powershell
.\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`:

```ini
[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:

```bash
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).