force cmu-onsite runner due to firewall

README.md

@@ -164,6 +164,45 @@ consequences worth knowing:
 CMU's publish CGI to make the files live. It also runs on pushes to `main` and can be triggered
 manually from the Gitea Actions UI.
 
+### Why an on-campus runner is required
+
+`linux.andrew.cmu.edu` (the SFTP target) is only reachable from **inside CMU's network**. A
+cloud/hosted Gitea runner sits on the public internet and cannot reach it, which is what causes
+`lftp` to fail with `max-retries exceeded`. The workflow is therefore pinned to a self-hosted
+runner via `runs-on: cmu-onsite`; only a runner registered with that label — running on a machine
+inside CMU's network — will pick up the job.
+
+### Setting up the `cmu-onsite` runner
+
+Run [`act_runner`](https://gitea.com/gitea/act_runner) on a machine that stays on CMU's network.
+Register it against this repo (or your Gitea instance) with the `cmu-onsite` label mapped to a
+Node-capable Docker image, so the workflow's `apt-get`/Node steps work unchanged:
+
+```bash
+# On the on-campus machine (Docker installed and running):
+act_runner register \
+  --instance https://your-gitea-host \
+  --token <REGISTRATION_TOKEN_FROM_GITEA> \
+  --name cmu-onsite-01 \
+  --labels 'cmu-onsite:docker://node:20-bookworm' \
+  --no-interactive
+
+# Then run it (or install as a service):
+act_runner daemon
+```
+
+Notes:
+
+- The registration token comes from Gitea under **Settings → Actions → Runners → Create new
+  runner** (repo-level) or the equivalent org/site-level page.
+- The `:docker://node:20-bookworm` suffix is what makes the label run jobs in a Debian container
+  with Node preinstalled. Without an image mapping the label would run directly on the host, and
+  the `sudo apt-get install lftp` step would need the tools present on the machine instead.
+- Confirm the runner host can actually reach the target before relying on it:
+  `nc -vz linux.andrew.cmu.edu 22`. Some CMU subnets are firewalled off from the timeshare hosts.
+- Keep the runner process up (systemd service, container restart policy, etc.) so the nightly
+  schedule fires.
+
 ### Required secrets
 
 Set these in your Gitea repo under **Settings → Actions → Secrets**:
@@ -197,10 +236,13 @@ the clocks change.
 
 - The SFTP password is passed to `lftp` via an environment variable interpolated into the command;
   keep it only in Gitea secrets, never in the repo.
-- Host-key checking is disabled on the runner (`sftp:auto-confirm yes`) because CMU's host key is
-  not pre-seeded there. The transfer is still encrypted, but this does not verify the server's
-  identity. If you want strict host-key verification, add the server's key to the runner and
-  remove that setting.
+- Host-key checking is disabled on the runner (via `StrictHostKeyChecking=no` in the SSH
+  connect-program) because CMU's host key is not pre-seeded there. The transfer is still encrypted,
+  but this does not verify the server's identity. If you want strict host-key verification, add the
+  server's key to the runner's `known_hosts` and remove that option.
+- The upload step runs `lftp` with `debug 3` and forces password auth over an explicit `ssh`
+  connect-program. This makes connection failures visible in the job log and re-enables a few older
+  key-exchange / host-key algorithms that some CMU hosts still require.
 
 ## Data persistence