mimic-big/docs/podman-runner-setup.md

Gitea Actions runner — Podman rootless runbook

Archived setup procedure for the gitea-runner host that drives Mimic CI (.gitea/workflows/ci.yml). Captures the corrections that emerged during sprint 0 install so future operators don't re-discover the same traps.

Target architecture

• Host : same VM as the Gitea server (sprint 0 deployment choice).
• Container runtime : Podman rootless under the existing gitea system user. No new account, no rootful daemon.
• Runner image : docker.io/gitea/act_runner:X.Y.Z (pinned, see Pin policy).
• Auto-start : Quadlet (~/.config/containers/systemd/<name>.container) — the upstream-recommended pattern since Podman 4.4. podman generate systemd is officially deprecated; do not introduce it.
• Label exposed to workflows : linux (single, kept short, matches the runs-on: linux line in .gitea/workflows/ci.yml).

Prerequisites on the host

Component	Requirement	Verify
Podman	≥ 4.4 (Quadlet support)	podman --version
Rootless mode	enabled	podman info --format '{{.Host.Security.Rootless}}' → true
systemd user mode	linger on for the runner user	loginctl show-user <user> | grep Linger
podman.socket user unit	available	ls /usr/lib/systemd/user/podman.socket
Gitea Actions	enabled in app.ini	[actions] ENABLED = true then restart

If Gitea Actions was never activated, edit /etc/gitea/app.ini:

[actions]
ENABLED = true

[actions.log_compression]
ENABLED = true

Restart with sudo systemctl restart gitea. The UI exposes Site Administration → Actions → Runners once enabled.

Pin policy

Never use :latest for the runner image in production. Pin a concrete gitea/act_runner:X.Y.Z tag and bump explicitly through this runbook. The same policy is tracked for every other production image in tasks/todo.md follow-up F-D1 (digest pinning roadmap).

To find the current release: https://gitea.com/gitea/act_runner/releases.

Step 1 — Switch to the runner user

sudo machinectl shell <user>@         # or: sudo -iu <user>
id                                     # capture $UID for later substitution
podman info --format '{{.Host.Security.Rootless}}'   # must print "true"

If loginctl show-user <user> | grep Linger reports Linger=no, run as root before going further:

sudo loginctl enable-linger <user>

Without linger the Podman user-mode socket dies when <user> logs out and the runner stops accepting jobs.

Step 2 — Activate the Podman socket

systemctl --user enable --now podman.socket
systemctl --user status podman.socket
ls -la /run/user/$(id -u)/podman/podman.sock     # exists, mode 0660

Step 3 — Pull the runner image

podman pull docker.io/gitea/act_runner:X.Y.Z      # replace X.Y.Z

Step 4 — Generate a baseline config

mkdir -p ~/.config/act_runner ~/.local/share/act_runner
cd ~/.config/act_runner
podman run --rm docker.io/gitea/act_runner:X.Y.Z \
  act_runner generate-config > config.yaml

Edit ~/.config/act_runner/config.yaml — only these keys matter:

runner:
  capacity: 2
  envs:
    DOCKER_HOST: "unix:///var/run/docker.sock"     # path as seen by the container
  labels:
    - "linux:docker://node:22-alpine"

container:
  network: "bridge"
  privileged: false
  docker_host: "unix:///var/run/docker.sock"
  options: "--security-opt label=disable"          # see SELinux note below

Step 5 — Register the runner (single-use token)

Gotcha — register pings the container daemon. Even though act_runner register writes no actual job, it sanity-checks at startup that it can reach a container runtime. Without the socket mounted, register fails with cannot ping container daemon and the credential file ~/.local/share/act_runner/.runner is never written. Mount the socket on the register one-shot too — not only on the daemon.

Generate a registration token in Site Administration → Actions → Runners → Create new Runner, then run once:

podman run --rm \
  --security-opt label=disable \
  -v ~/.config/act_runner/config.yaml:/config.yaml \
  -v ~/.local/share/act_runner:/data \
  -v /run/user/$(id -u)/podman/podman.sock:/var/run/docker.sock \
  -w /data \
  -e GITEA_INSTANCE_URL=https://repo.try2get.in \
  -e GITEA_RUNNER_REGISTRATION_TOKEN=<TOKEN_FROM_GITEA_UI> \
  -e GITEA_RUNNER_NAME=gitea-runner \
  -e GITEA_RUNNER_LABELS=linux \
  docker.io/gitea/act_runner:X.Y.Z \
  act_runner register --no-interactive

The token is single-use: invalidated the moment register succeeds. Generate a fresh one for each re-registration.

Secret handling convention. Do not paste the registration token into chat, agent transcripts, or issue trackers. Drop it on disk (e.g. ~/runner-token.txt), cat it into the environment for the one-shot above, then shred -u the file. This mirrors the team-lead "secrets via file, not chat" rule.

Verify the runner appears in the Gitea UI at https://repo.try2get.in/-/admin/actions/runners with status idle.

Step 6 — Quadlet unit (auto-start)

~/.config/containers/systemd/gitea-runner.container :

[Unit]
Description=Gitea Actions Runner (Mimic) — Podman rootless
After=podman.socket
Requires=podman.socket

[Container]
Image=docker.io/gitea/act_runner:X.Y.Z
ContainerName=gitea-runner
SecurityLabelDisable=true
Volume=%h/.config/act_runner/config.yaml:/config.yaml,ro
Volume=%h/.local/share/act_runner:/data
Volume=/run/user/%U/podman/podman.sock:/var/run/docker.sock
WorkingDir=/data
Exec=act_runner daemon --config /config.yaml

[Service]
Restart=on-failure
RestartSec=5
TimeoutStartSec=900

[Install]
WantedBy=default.target

Notes:

• %h expands to the runner user's $HOME, %U to the runner user's UID. Hardcoding 1000 (or any specific UID) was a sprint 0 mistake — the actual gitea UID on this host is 1005. Quadlet substitution makes the unit portable across hosts.
• SecurityLabelDisable=true is the Quadlet equivalent of --security-opt label=disable. It bypasses SELinux container labelling so the rootless container can read+write the host Podman socket. On SELinux-disabled systems (Debian/Ubuntu vanilla) this is a no-op; on RHEL/Fedora-like it is required — without it nginx-style "Permission denied" appears on socket connect.

Activate:

systemctl --user daemon-reload
systemctl --user start gitea-runner.service       # generated from .container
systemctl --user enable gitea-runner.service      # persist across reboots
journalctl --user -u gitea-runner.service -e

Quadlet generates gitea-runner.service automatically; do not create it by hand under ~/.config/systemd/user/.

Step 7 — Smoke validation

Push a transient workflow on a feature branch. Example used during sprint 0 (file lived at .gitea/workflows/smoke.yml on chore/podman-and-ci, removed after green):

name: smoke
on:
  push:
    branches: [chore/podman-and-ci]
  workflow_dispatch:

jobs:
  hello:
    runs-on: linux
    steps:
      - run: |
          echo "host: $(uname -a)"
          id
          head -3 /etc/os-release

Job picked up and green within ~10 s on the Gitea Actions tab → runner is operational. Failures usually trace back to one of the gotchas captured above (journalctl --user -u gitea-runner.service -e is authoritative).

Step 8 — Repo secrets

CI consumes the following secrets, configured per repo at <repo>/settings/actions/secrets:

Secret	Use	Value
FERNET_KEY_TEST	MIMIC_FERNET_KEY in CI jobs	python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())" once, fixed thereafter

Never reuse production Fernet material in CI.

Decommissioning

# As the runner user:
systemctl --user disable --now gitea-runner.service
rm ~/.config/containers/systemd/gitea-runner.container
systemctl --user daemon-reload
rm -rf ~/.config/act_runner ~/.local/share/act_runner
# Drop the runner entry in Gitea UI: Site Admin → Actions → Runners → Delete.

The Podman socket and linger setting stay — they are user-level and shared with anything else the user runs.

Cross-references

• Sprint 0 decisions: tasks/spec-decisions.md (D-007 reverse proxy scope, D-010 Ansible playbook scope).
• CI workflow: .gitea/workflows/ci.yml.
• Deferred CI work: tasks/todo.md section "CI follow-ups (sprint 1+)".