feat: Enhance CI workflows by adding linting step, updating documentation, and configuring development dependencies

docs/architecture/07_deployment/07_03_gitea_action_runner.md

@@ -0,0 +1,152 @@
+# 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).