PacketStation/deploy/runner/README.md

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)

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