Gitea Actions runner for docker-1 (deploy/runner), DEPLOY.md and PLAN.md notes

Co-Authored-By: Claude Fable 5.1 <[email protected]>

CHANGELOG.md

@@ -16,6 +16,7 @@ All notable changes to this project are recorded here. The format follows [Keep
 - Frontend: the home layout (headline, KPIs, attention, find bar with the basic search and the two-step project and unit picker, boards and list view), the Clerical screen (Changes to approve, Flagged, Going to the warehouse, Ready to close, Ready for data book, Filed; projects and units with new project and unit sheets, renumbering, move packet), the packet page (header, Drawing tab with pdf.js, Materials, Work orders with QR codes, Documents, History) with every control driven by `can` and `blocked`, hand-made draft creation, the heat map question, send to warehouse, send straight to a department or Q.C., signature and IT reason sheets, live refresh from server events.
 - Tests: the full policy matrix (every transition as every role in every status), custody, short-parts and change-order exceptions, preconditions, compare-and-set conflicts and row versions per table, server-assigned numbers under concurrent inserts, the audit and packet log rows, projects and units, assets. A Playwright scenario for the Clerical draft flow against the CI stack.
 - `/api/departments` now returns station ids and the weld flag.
+- deploy/runner: the Gitea Actions runner for docker-1 (compose file, act_runner config, install notes); registered on docker-1.
 - Phase 1: identity. Sign-in with the domain account and password against PESCO's Active Directory over LDAPS (search with the service account, then bind as the user; nested groups resolved; disabled accounts refused). Roles are the union of a person's `PS-*` groups, mapped by a table derived from the department list.
 - Server-side sessions: HttpOnly, SameSite=Strict cookie, idle sign-out after 15 minutes, absolute 12 hours for password sessions and 10 hours for PIN sessions, server-recorded lock after 3 idle minutes or a tab hidden for over a minute, step-up unlock with PIN or password. Origin and `X-Requested-With` check on every state-changing request.
 - Optional Packet Station PIN, 6 to 12 digits, set by the user with their domain password, hashed with Argon2id. PIN sign-in by employee ID on registered devices only. Five wrong attempts disable the PIN; three wrong attempts at unlock or signature end the session.

deploy/runner/README.md

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

deploy/runner/compose.yaml

@@ -0,0 +1,36 @@
+# Gitea Actions runner for docker-1. One act_runner container with the host Docker socket.
+# Jobs run in docker.gitea.com/runner-images:ubuntu-latest containers started through the socket;
+# the runner's Docker proxy lets a job's `docker compose` bind-mount the workspace by its own path,
+# which is what the e2e job needs for deploy/compose.ci.yaml.
+#
+# Install on docker-1 (see README.md): copy this folder to ~/gitea/runner, register once, then up -d.
+#   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
+# The registration token goes straight from Gitea into the register command. It is never written down.
+
+name: gitea-runner
+
+services:
+  runner:
+    # docker.gitea.com/act_runner:0.4 (act_runner v0.4.1), pinned by digest 2026-10-16.
+    # To refresh: docker buildx imagetools inspect docker.gitea.com/act_runner:0.4
+    image: docker.gitea.com/act_runner:0.4@sha256:696a59b51ad3d149521e3beb0229d5fb88f87295e1616f940199793274415b56
+    environment:
+      CONFIG_FILE: /data/config.yaml
+      # Registration happens once, by hand, with the command above. These two are only read on an
+      # unregistered start and are left here so the names are known; no token is set in this file.
+      GITEA_INSTANCE_URL: https://gt.pescoinc.biz
+      GITEA_RUNNER_NAME: docker-1
+    volumes:
+      - ./data:/data                                   # .runner (the registration), config.yaml, cache, job logs
+      - /var/run/docker.sock:/var/run/docker.sock      # job containers and the Docker proxy
+    restart: unless-stopped
+    logging:
+      driver: json-file
+      options:
+        max-size: "10m"
+        max-file: "5"

deploy/runner/config.yaml

@@ -0,0 +1,27 @@
+# act_runner configuration for the docker-1 runner. Every value not set here keeps the runner's default.
+# Reference: https://gitea.com/gitea/act_runner/src/branch/main/internal/pkg/config/config.example.yaml
+
+log:
+  level: info
+  job:
+    dir: /data/logs       # a copy of each job log, kept a week
+    retention: 168h
+
+runner:
+  file: /data/.runner
+  capacity: 2             # server and frontend jobs run side by side; the e2e job is heavy on its own
+  timeout: 1h
+  labels:
+    - "ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latest"
+
+cache:
+  enabled: true
+  dir: /data/cache
+
+container:
+  # The job workspace is a Docker volume; the Docker proxy maps workspace paths for sibling
+  # containers, so `docker compose` in the e2e job can bind-mount tests/e2e and deploy/postgres/initdb.
+  privileged: false
+  valid_volumes: []
+  # The proxy removes what a job started (the CI compose stack included) when the job ends.
+  sweep: true

docs/DEPLOY.md

@@ -158,6 +158,23 @@ The DC runs with `cap_add: [SYS_ADMIN]`, which Samba needs to set the sysvol ACL
 
 The real PESCO domain controllers are never used by CI. The test and production stacks do not run the DC.
 
+## Gitea Actions runner (phase 2)
+
+`.gitea/workflows/ci.yml` runs on a Gitea Actions runner named `docker-1`, installed on docker-1 at
+`~/gitea/runner` from [deploy/runner/](../deploy/runner/): one `act_runner` container (pinned by digest) with
+the host Docker socket, label `ubuntu-latest` mapped to `docker.gitea.com/runner-images:ubuntu-latest`,
+capacity 2. The server, frontend and image jobs run in job containers from that image. The e2e job starts
+the CI compose stack through the runner's Docker proxy on docker-1's daemon, which maps the job workspace so
+the stack's bind mounts resolve and removes the stack when the job ends. The runner was registered on
+2026-10-16 with a token generated by `gitea actions generate-runner-token` inside the `gitea` container; the
+token was never written down. [deploy/runner/README.md](../deploy/runner/README.md) has the install, update
+and re-register steps.
+
+The repository must exist on Gitea (`spencerm/packetstation`) with Actions enabled, and the image job needs
+the repository secrets `REGISTRY_USER` and `REGISTRY_TOKEN` (a Gitea token with package write). Until the
+first push, the workflow has not run on the runner; open question 15 in PLAN.md records what is still to be
+seen (the Samba DC's `cap_add` through the proxy).
+
 ## Backup (planned, phase 9)
 
 `pg_dump` of both stacks from a systemd timer on the host at 02:00 America/Denver, before the 03:00 PBS run. Seven dumps kept in `/var/backups/packetstation/<stack>/` with last-success and last-failure markers. The worker's backup-check job alerts if the newest dump is missing or older than 26 hours. Scripts and units go in `scripts/`.

docs/PLAN.md

@@ -232,7 +232,7 @@ Smaller questions from the design, with the default the build takes unless told
 12. Partspecs, title or folded-operation target changes on an in-shop packet: default no change order, as the old build.
 13. Work-order-gone confirmation after 2 consecutive runs and the 10% suspect-batch guard: defaults as stated.
 14. Pause scope: default pauses the feed, the drawing job and auto-release together.
-15. Gitea runner: whether the Samba DC container can run there (overlayfs xattrs, possibly cap SYS_ADMIN). Checked in phase 1; if not, CI uses a runner with a Docker socket on docker-1. Phase 1 finding (2026-10-16): the container needs `cap_add: [SYS_ADMIN]` (Samba 4.17 sets sysvol NT ACLs through `security.*` xattrs) and runs that way on docker-1; the Gitea runner itself is still to be tried.
+15. Gitea runner: whether the Samba DC container can run there (overlayfs xattrs, possibly cap SYS_ADMIN). Checked in phase 1; if not, CI uses a runner with a Docker socket on docker-1. Phase 1 finding (2026-10-16): the container needs `cap_add: [SYS_ADMIN]` (Samba 4.17 sets sysvol NT ACLs through `security.*` xattrs) and runs that way on docker-1; the Gitea runner itself is still to be tried. Phase 2 (2026-10-16): an act_runner with the host Docker socket is registered on docker-1 as `docker-1` (deploy/runner/); the first workflow run, after the repository is pushed to Gitea, shows whether its Docker proxy passes `cap_add` to the DC.
 16. NPM: confirm `Block common exploits` does not interfere with uploads; checked when the test proxy host is made in phase 0.
 17. SET_DATABOOK_AT is writable by anyone in the old build, even when filed: default restrict to Clerical and Q.C.
 18. CO verifications cannot be withdrawn; ITP line signatures can be undone by the same inspector or an Admin before the block is signed.