furtka/docs/runner-setup.md

# Forgejo Runner Setup

How to stand up a `forgejo-runner` so the CI workflow in `.forgejo/workflows/ci.yml` actually executes on every push.

The runner is a long-running daemon that polls the Forgejo instance for queued jobs and runs them in Docker containers.

A ready-to-use bootstrap script and compose file live under [`ops/forgejo-runner/`](../ops/forgejo-runner/).

## Choosing a host

| Option | Good for | Trade-off |
|--------|----------|-----------|
| **Dedicated VPS** | Production-ish CI that runs even when you're offline | Costs a few €/month; one more machine to maintain |
| **Home server / NAS** | Free; plenty of capacity | CI blocked if home network / power drops |
| **Local dev machine** | Quick to set up, fast runs | CI only works while the machine is on |

Recommendation for now: **home server or a cheap VPS**. Don't use a laptop that suspends.

## Install

Pick either the binary or the Docker container path. Docker is easier to upgrade.

### Path A: Docker Compose (recommended)

Copy `ops/forgejo-runner/compose.yml` and `ops/forgejo-runner/config.yml` from this repo to the host, e.g. into `~/forgejo-runner/` (compose file) and `~/forgejo-runner/data/` (config file). The runner talks to a sidecar Docker-in-Docker container via `tcp://docker-in-docker:2375`, so the host's own Docker socket is not exposed to jobs.

If the host is a fresh Ubuntu VM, run `ops/forgejo-runner/bootstrap.sh` first to install Docker Engine + the Compose plugin from the official repo.

### Path B: Binary

Download the latest release from https://code.forgejo.org/forgejo/runner/releases and drop it somewhere in `$PATH`:

```bash
wget https://code.forgejo.org/forgejo/runner/releases/download/v6.0.0/forgejo-runner-6.0.0-linux-amd64
chmod +x forgejo-runner-6.0.0-linux-amd64
sudo mv forgejo-runner-6.0.0-linux-amd64 /usr/local/bin/forgejo-runner
```

## Register

1. In the Forgejo web UI: go to **Site Administration → Actions → Runners → Create new Runner**. Copy the registration token. (For a repo-scoped runner instead, use **Repo Settings → Actions → Runners**.)

2. Register from the runner host by running the registration inside a one-shot container so the output lands in the mounted `data/` directory:

   ```bash
   cd ~/forgejo-runner
   docker run --rm -v "$PWD/data:/data" code.forgejo.org/forgejo/runner:6 \
     forgejo-runner register \
       --instance https://forgejo.sourcegate.online \
       --token <TOKEN> \
       --name forge-runner-01 \
       --labels 'docker:docker://catthehacker/ubuntu:act-latest,ubuntu-latest:docker://catthehacker/ubuntu:act-latest,self-hosted:docker://catthehacker/ubuntu:act-latest' \
       --no-interactive
   ```

   Labels *must* use the `<name>:docker://<image>` form — bare labels (`ubuntu-latest`) get stored as `ubuntu-latest:host`, which tells the runner to execute jobs directly inside the runner container (no Python, no git, nothing). `catthehacker/ubuntu:act-latest` is the common drop-in image with GitHub Actions tooling preinstalled.

3. Start the daemon: `docker compose up -d`.

4. Verify the runner shows up as **Idle** in Forgejo's admin Runners page and the log prints `runner: forge-runner-01, ..., declared successfully`.

## First CI run

Push any commit; the Actions tab on the repo should show the workflow running. If nothing happens:

- Confirm the runner is online (Forgejo admin → Actions → Runners).
- Check the workflow has labels that match the runner (`runs-on: ubuntu-latest` needs a runner registered with that label).
- Check the runner logs: `docker logs forgejo-runner` or the systemd journal.

## Systemd unit (for the binary path)

```ini
[Unit]
Description=Forgejo Actions Runner
After=docker.service
Requires=docker.service

[Service]
ExecStart=/usr/local/bin/forgejo-runner daemon
WorkingDirectory=/var/lib/forgejo-runner
User=forgejo-runner
Restart=on-failure

[Install]
WantedBy=multi-user.target
```

Save as `/etc/systemd/system/forgejo-runner.service`, then `sudo systemctl enable --now forgejo-runner`.

## Security notes

- Jobs run inside a Docker-in-Docker sidecar, not against the host's Docker socket. Still, DinD runs privileged — give the runner its own VM, not a shared host.
- Registration tokens are one-shot; a stolen token can't re-register after the runner is live.
- Prefer repo-scoped runners over instance-wide if you're sharing the runner with other repos you don't control.
- Ubuntu's default systemd-resolved makes the host's stub resolver (`127.0.0.53`) inherit a LAN DNS server that Docker containers may not be able to reach. If container DNS fails, set explicit upstream DNS in `/etc/docker/daemon.json` (e.g. `{"dns": ["1.1.1.1", "8.8.8.8"]}`) and `sudo systemctl restart docker`.