# Gitea Actions runner on docker-1

`.gitea/workflows/ci.yml` runs on a Gitea Actions runner. This folder holds the runner's compose file and
configuration. It lives on docker-1 at `~/gitea/runner`, next to the Gitea compose project, and runs as
the `spencerm` user through the Docker socket. No sudo is needed.

## What it runs

- One `act_runner` container (`docker.gitea.com/act_runner`, pinned by digest in compose.yaml), named
  `docker-1` in Gitea, with the label `ubuntu-latest` mapped to `docker.gitea.com/runner-images:ubuntu-latest`
  (Ubuntu 24.04 with git, node, python 3.12, docker and compose).
- Every job of ci.yml runs in a fresh job container from that image. The server job's PostgreSQL service
  container and the e2e job's compose stack (postgres, migrate, app, worker, the Samba DC, Playwright) are
  started through the runner's Docker proxy on docker-1's daemon. The proxy maps the job workspace so the
  compose bind mounts (`deploy/postgres/initdb`, `tests/e2e`, the CI secrets) resolve, and it removes what
  the job started when the job ends.
- Capacity 2: server and frontend run at the same time; e2e waits for both.

## Install (once)

```bash
mkdir -p ~/gitea/runner/data
cp deploy/runner/compose.yaml ~/gitea/runner/
cp deploy/runner/config.yaml ~/gitea/runner/data/
cd ~/gitea/runner
docker compose run --rm --entrypoint act_runner runner register --no-interactive \
  --instance https://gt.pescoinc.biz --name docker-1 --config /data/config.yaml \
  --labels ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latest \
  --token "$(docker exec -u git gitea gitea actions generate-runner-token)"
docker compose up -d
docker compose logs --tail 20 runner
```

The registration token is generated by Gitea's own CLI inside the `gitea` container and goes straight
into the register command. It is never printed or written to a file. The result is `data/.runner`,
which holds the runner's own token: keep the `data` folder private (it is owned by `spencerm`).

## Operate

- Logs: `docker compose -f ~/gitea/runner/compose.yaml logs -f runner`. Job logs are also kept under
  `~/gitea/runner/data/logs` for a week.
- Update: change the digest in compose.yaml (`docker buildx imagetools inspect docker.gitea.com/act_runner:0.4`),
  then `docker compose up -d`. The registration survives updates.
- Re-register (new instance URL or labels): remove `data/.runner` and run the register command again.
  Gitea keeps the old runner row; delete it in Site administration, Actions, Runners.
- The runner shows in Gitea under Site administration, Actions, Runners. Repository secrets for the
  image job (`REGISTRY_USER`, `REGISTRY_TOKEN`) are set per repository under Settings, Actions, Secrets.

## Known limits

- The job images and the actions (`actions/checkout`, `setup-python`, `setup-node`, the docker ones) are
  fetched from docker.gitea.com, GitHub and GitHub releases, so docker-1 needs outbound internet.
- The Samba DC in the e2e stack needs `cap_add: SYS_ADMIN`. The first run on this runner shows whether the
  Docker proxy allows it; if not, the e2e job stays a by-hand step (docs/DEPLOY.md).