diff --git a/.github/fork-fleet.json b/.github/fork-fleet.json index af0b2cb0a126..8507cefb0358 100644 --- a/.github/fork-fleet.json +++ b/.github/fork-fleet.json @@ -26,12 +26,12 @@ }, "pools": [ { - "_doc": "The owner's PC: its dispatcher runs on the always-on host and starts runners on the PC over ssh.", + "_doc": "The owner's PC, a desk pool: its desk agent dials out to the always-on host, whose dispatcher for this pool starts runners on the PC through that link (fork-fleet.md, The desk link).", "name": "pc", "label": "fleet-pc-t3code", "slots": 1, "beacon": "FLEET_BEACON_PC", - "launch": ["/opt/fork-fleet/launch-pc"], + "launch": ["python3", "-I", "/opt/fork-fleet/fork-fleet-desk.py", "launch", "pc"], "waits": false }, { diff --git a/.github/fork-fleet.md b/.github/fork-fleet.md index 77e778db8d2b..c6497b9b12db 100644 --- a/.github/fork-fleet.md +++ b/.github/fork-fleet.md @@ -449,6 +449,7 @@ done scripts/fork-fleet-hook.sh:hook.sh:755 scripts/fork-fleet-launch.sh:fork-fleet-launch.sh:755 scripts/fork-fleet-desk.py:fork-fleet-desk.py:644 scripts/fork-fleet-desk-wire.py:fork-fleet-desk-wire.py:644 scripts/fork-fleet-desk-seed.py:fork-fleet-desk-seed.py:644 + scripts/fork-fleet-desk-key.py:fork-fleet-desk-key.py:644 scripts/fork-fleet-refresh.service:fork-fleet-refresh.service:644 scripts/fork-fleet-refresh.timer:fork-fleet-refresh.timer:644 scripts/fork-fleet-job-paths.txt:fork-fleet-job-paths.txt:644" @@ -572,10 +573,15 @@ Do not name the dispatcher's unit `fork-fleet-*`: that prefix is for runner units. Runner units are separate transient units, so restarting the dispatcher leaves running jobs alone. -**The `pc` pool** stays off until `/opt/fork-fleet/launch-pc` exists: a wrapper -that runs `fork-fleet-launch.sh` on the PC over ssh. Run the dispatcher with -`--pool vm` until then. Without its dispatcher, `pc` has no heartbeat, and -`route` never counts it. Whether and how the PC joins is an owner decision. +**The `pc` pool** is a desk pool: the owner's PC, through the desk link below. +It stays off until its own dispatcher unit runs (`t3code-fleet-dispatcher-pc`, +"One dispatcher per desk pool") and the PC's desk key is added: without its +dispatcher, `pc` has no heartbeat and `route` never counts it. While the PC +sleeps or is off, `launch` exits 3 at once and its jobs go elsewhere. A host +that ran an older `pc` dispatcher on `/opt/fork-fleet/launch-pc` first stops +that dispatcher and lets its runners finish (this config's cleanup skips a pool +that is down, so it never stops or prunes them); then it may delete the +wrapper: nothing reads it. ### The desk link (a desktop pool) @@ -585,7 +591,7 @@ out to the always-on host over ssh, as a dedicated unprivileged user (default pool. The pool's dispatcher on the always-on host sends the launcher's verbs through that one session (`fork-fleet-desk.py`, its wire format `fork-fleet-desk-wire.py`). Once per always-on host, as root (step 3 installs -both files): +these files and the key tool `fork-fleet-desk-key.py`): ```sh # The desk-link user: a real shell (sshd runs the forced command through it, so nologin would close the link) and no @@ -596,7 +602,7 @@ usermod -p '*' fleet-desk echo 'd /run/fork-fleet-desk 0710 fleet-desk fleet-desk -' > /etc/tmpfiles.d/fork-fleet-desk.conf systemd-tmpfiles --create /etc/tmpfiles.d/fork-fleet-desk.conf # Per desk pool: the desktop's public key, as the desk-link user, with the key tool fork-fleet-desk-key.py -# (row D4 of the desktop-pool design; install it beside the others). +# (step 3 installs it). sudo -u fleet-desk -H /usr/bin/python3 -I /opt/fork-fleet/fork-fleet-desk-key.py --config /opt/fork-fleet/fork-fleet.json add POOL < desk-POOL.pub ``` @@ -610,6 +616,24 @@ Another user name: use it in all three places above, and give the dispatcher tmpfiles line; the desk-link user must be in it, and so must the dispatcher's user when that is not root. +A desk pool's entry in a project's fleet config (made-up names; `seeds` is +optional, see "Seeds" below): + +```json +{ + "name": "desktop", + "label": "fleet-desktop-example", + "slots": 2, + "beacon": "FLEET_BEACON_DESKTOP", + "launch": ["python3", "-I", "/opt/fork-fleet/fork-fleet-desk.py", "launch", "desktop"], + "waits": false +} +``` + +`waits: false`: a desktop may sleep, so a job never waits for it. `slots` at +most the desktop's own `slots` (its machine file). The pool's name is the one in +the desktop's machine file and in the key line. + `serve` keeps one session per pool (a lock), listens on a 0660 socket in `/run/fork-fleet-desk` (it lets in only root, its own user and the socket group), and pings the agent; `launch` fails at once (exit 3) when no session is diff --git a/.github/scripts/fork-fleet-desk-key.test.py b/.github/scripts/fork-fleet-desk-key.test.py index 9ee61a0527b2..2ef0720d2695 100644 --- a/.github/scripts/fork-fleet-desk-key.test.py +++ b/.github/scripts/fork-fleet-desk-key.test.py @@ -54,7 +54,10 @@ def setUp(self): self.home = os.path.join(self.tmp, 'home') os.mkdir(self.home) cfg = dk.ff.load() - cfg['pools'] = cfg['pools'] + [desk('desk'), desk('desk2')] + # only this test's desk pools: the release's own desk pool (pc) is left out by name, never by the function + # under test; vm stays, so a non-desk pool is always there to be refused + cfg['pools'] = [p for p in cfg['pools'] if p['name'] != 'pc'] + [desk('desk'), desk('desk2')] + assert 'vm' in [p['name'] for p in cfg['pools']] self.config = os.path.join(self.tmp, 'fleet.json') with open(self.config, 'w') as f: json.dump(cfg, f) @@ -151,7 +154,7 @@ def test_refuses_anything_but_one_valid_ed25519_public_key(self): self.assertIn('private key', self.run_tool('add', 'desk', stdin=PRIVATE)[1]) def test_refuses_a_pool_it_does_not_know(self): - for pool in ('nope', 'vm', 'pc', '../desk', 'desk "x"'): + for pool in ('nope', 'vm', '../desk', 'desk "x"'): with self.subTest(pool): code, out = self.run_tool('add', pool, stdin=PUB1) self.assertEqual(code, REFUSED, out) diff --git a/.github/scripts/fork-fleet-refresh.test.py b/.github/scripts/fork-fleet-refresh.test.py index ea6fe0b0ac85..caa1fcc7912b 100755 --- a/.github/scripts/fork-fleet-refresh.test.py +++ b/.github/scripts/fork-fleet-refresh.test.py @@ -967,12 +967,14 @@ def test_the_service_cannot_write_run_dir(self): def test_the_service_writes_the_templates_own_folder_only(self): """The writable folder is the default template's own folder, and none of the files root runs (the launcher, - the dispatcher, its trust config, the job hook, the pc wrapper) is in it or under it.""" + the dispatcher, its trust config, the job hook, the desk link and its wire format, seed and key tools) is in it + or under it.""" service = unit('fork-fleet-refresh.service')['Service'] rw = [p.lstrip('-') for p in service['ReadWritePaths'].split()] self.assertEqual(rw, [os.path.dirname(default_template())]) root_dir = os.path.dirname(service['ExecStart'].split()[0]) - for f in ('fork-fleet-launch.sh', 'fork-fleet.py', 'fork-fleet.json', 'hook.sh', 'launch-pc', 'SOURCE'): + for f in ('fork-fleet-launch.sh', 'fork-fleet.py', 'fork-fleet.json', 'hook.sh', 'fork-fleet-desk.py', + 'fork-fleet-desk-wire.py', 'fork-fleet-desk-seed.py', 'fork-fleet-desk-key.py', 'SOURCE'): path = f'{root_dir}/{f}' self.assertFalse(any(path == w or path.startswith(w.rstrip('/') + '/') for w in rw), path) self.assertNotIn('AF_UNIX', service['RestrictAddressFamilies'].split()) diff --git a/FORK_CHANGES.md b/FORK_CHANGES.md index 83ae5032ac68..8c89854bb806 100644 --- a/FORK_CHANGES.md +++ b/FORK_CHANGES.md @@ -35,21 +35,21 @@ is missing here or a setting named here does not exist. These change only how this repository is built, tested and released, not the app. -| Change | Why | Setting | Default | PR | -| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ----------------------------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Fork release workflow: builds `v.fork.` with the Linux and Windows CLI archives and unsigned desktop apps. | The fork needs its own releases to install and update from. | none | run by hand or by fork-follow | [#2](https://github.com/scuttletoby/t3code/pull/2) | -| fork-follow: once a day, rebase the fork onto upstream's newest tag, test, and release only when green; on trouble, open one issue. | Stay close to upstream without manual work. | repository variable `FORK_FOLLOW_CHANNEL` | `nightly` | [#4](https://github.com/scuttletoby/t3code/pull/4), [#22](https://github.com/scuttletoby/t3code/pull/22), [#66](https://github.com/scuttletoby/t3code/pull/66) | -| Fork tests: upstream's test jobs, run on GitHub-hosted runners or on the repository's own machines chosen per run. | Fast CI that does not need upstream's runner labels. | repository variable `CI_RUNNERS` | `auto` | [#6](https://github.com/scuttletoby/t3code/pull/6), [#8](https://github.com/scuttletoby/t3code/pull/8), [#13](https://github.com/scuttletoby/t3code/pull/13) | -| Fleet runners: one-job runners started on demand on the repository's own machines, each behind walls, plus a link from a desktop machine. | Use spare machines for CI without letting a job reach the host. | repository variable `CI_RUNNERS` | `auto` | [#53](https://github.com/scuttletoby/t3code/pull/53), [#74](https://github.com/scuttletoby/t3code/pull/74), [#191](https://github.com/scuttletoby/t3code/pull/191), [#192](https://github.com/scuttletoby/t3code/pull/192), [#194](https://github.com/scuttletoby/t3code/pull/194), [#195](https://github.com/scuttletoby/t3code/pull/195), [#196](https://github.com/scuttletoby/t3code/pull/196), [#197](https://github.com/scuttletoby/t3code/pull/197), [#198](https://github.com/scuttletoby/t3code/pull/198), [#205](https://github.com/scuttletoby/t3code/pull/205), [#208](https://github.com/scuttletoby/t3code/pull/208) | -| Checks that refuse database schema and migration changes, fork changes to some upstream files, and fork lines outside the pinned seams. | Keep the fork thin, so upstream syncs stay easy and a database never needs a fork step. | none | always | [#3](https://github.com/scuttletoby/t3code/pull/3), [#97](https://github.com/scuttletoby/t3code/pull/97), [#185](https://github.com/scuttletoby/t3code/pull/185) | -| Pull requests from outside run nothing; four outside-started upstream workflows and `issue-vouch.yml` are deleted and kept deleted. | No code from an outside pull request runs with this repository's runners or tokens. | none | always | [#12](https://github.com/scuttletoby/t3code/pull/12), [#14](https://github.com/scuttletoby/t3code/pull/14), [#23](https://github.com/scuttletoby/t3code/pull/23) | -| A weekly check that the repository's interaction limit never lapses. | Outsiders cannot post while the limit holds. | none | always | [#30](https://github.com/scuttletoby/t3code/pull/30) | -| Secret scan on every push and pull request. | The fork is public: no token or key may land in it. | none | always | [#75](https://github.com/scuttletoby/t3code/pull/75), [#206](https://github.com/scuttletoby/t3code/pull/206), [#207](https://github.com/scuttletoby/t3code/pull/207), [#212](https://github.com/scuttletoby/t3code/pull/212) | -| fork-ci: CI actions any repository can pin (docs-scope, gradle-cache, job-changed, fleet-route, ci-demand, pinned), with their own releases. | Shared CI building blocks, kept general. | none | only where pinned | [#15](https://github.com/scuttletoby/t3code/pull/15), [#16](https://github.com/scuttletoby/t3code/pull/16), [#27](https://github.com/scuttletoby/t3code/pull/27), [#35](https://github.com/scuttletoby/t3code/pull/35), [#55](https://github.com/scuttletoby/t3code/pull/55), [#94](https://github.com/scuttletoby/t3code/pull/94), [#113](https://github.com/scuttletoby/t3code/pull/113), [#141](https://github.com/scuttletoby/t3code/pull/141) | -| fork-ci PR queue: merges armed pull requests in order once their reviews and checks pass. | Merges without someone watching each pull request. | none | only where used | [#18](https://github.com/scuttletoby/t3code/pull/18), [#19](https://github.com/scuttletoby/t3code/pull/19), [#20](https://github.com/scuttletoby/t3code/pull/20), [#21](https://github.com/scuttletoby/t3code/pull/21), [#32](https://github.com/scuttletoby/t3code/pull/32), [#61](https://github.com/scuttletoby/t3code/pull/61), [#70](https://github.com/scuttletoby/t3code/pull/70), [#71](https://github.com/scuttletoby/t3code/pull/71) | -| fork-ci head check and head gate: the queue's required check, posted by a GitHub App and judged by the default branch's code. | A pull request cannot fake its own required check. See [gate trust](docs/fork/gate-trust.md). | none | only where used | [#33](https://github.com/scuttletoby/t3code/pull/33), [#85](https://github.com/scuttletoby/t3code/pull/85), [#87](https://github.com/scuttletoby/t3code/pull/87) | -| Host kits (`fork-kit/`): `gh-apps` (GitHub App tokens for agents), `heavy` (run builds in a capped slice), `golive` (move a boot service to a new build; core and `check` so far). | Things the fork installs on a machine, each with an installer, a self-check and tests. | none | only when installed | [#86](https://github.com/scuttletoby/t3code/pull/86), [#173](https://github.com/scuttletoby/t3code/pull/173), [#182](https://github.com/scuttletoby/t3code/pull/182), [#183](https://github.com/scuttletoby/t3code/pull/183) | -| Design notes: host tools (agents on a person's own computer). | Design for review; no code yet. | none | - | [#26](https://github.com/scuttletoby/t3code/pull/26) | +| Change | Why | Setting | Default | PR | +| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ----------------------------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Fork release workflow: builds `v.fork.` with the Linux and Windows CLI archives and unsigned desktop apps. | The fork needs its own releases to install and update from. | none | run by hand or by fork-follow | [#2](https://github.com/scuttletoby/t3code/pull/2) | +| fork-follow: once a day, rebase the fork onto upstream's newest tag, test, and release only when green; on trouble, open one issue. | Stay close to upstream without manual work. | repository variable `FORK_FOLLOW_CHANNEL` | `nightly` | [#4](https://github.com/scuttletoby/t3code/pull/4), [#22](https://github.com/scuttletoby/t3code/pull/22), [#66](https://github.com/scuttletoby/t3code/pull/66) | +| Fork tests: upstream's test jobs, run on GitHub-hosted runners or on the repository's own machines chosen per run. | Fast CI that does not need upstream's runner labels. | repository variable `CI_RUNNERS` | `auto` | [#6](https://github.com/scuttletoby/t3code/pull/6), [#8](https://github.com/scuttletoby/t3code/pull/8), [#13](https://github.com/scuttletoby/t3code/pull/13) | +| Fleet runners: one-job runners started on demand on the repository's own machines, each behind walls, plus a link from a desktop machine. | Use spare machines for CI without letting a job reach the host. | repository variable `CI_RUNNERS` | `auto` | [#53](https://github.com/scuttletoby/t3code/pull/53), [#74](https://github.com/scuttletoby/t3code/pull/74), [#191](https://github.com/scuttletoby/t3code/pull/191), [#192](https://github.com/scuttletoby/t3code/pull/192), [#194](https://github.com/scuttletoby/t3code/pull/194), [#195](https://github.com/scuttletoby/t3code/pull/195), [#196](https://github.com/scuttletoby/t3code/pull/196), [#197](https://github.com/scuttletoby/t3code/pull/197), [#198](https://github.com/scuttletoby/t3code/pull/198), [#205](https://github.com/scuttletoby/t3code/pull/205), [#208](https://github.com/scuttletoby/t3code/pull/208), [#229](https://github.com/scuttletoby/t3code/pull/229), [#230](https://github.com/scuttletoby/t3code/pull/230), [#236](https://github.com/scuttletoby/t3code/pull/236), [#237](https://github.com/scuttletoby/t3code/pull/237), [#238](https://github.com/scuttletoby/t3code/pull/238) | +| Checks that refuse database schema and migration changes, fork changes to some upstream files, and fork lines outside the pinned seams. | Keep the fork thin, so upstream syncs stay easy and a database never needs a fork step. | none | always | [#3](https://github.com/scuttletoby/t3code/pull/3), [#97](https://github.com/scuttletoby/t3code/pull/97), [#185](https://github.com/scuttletoby/t3code/pull/185) | +| Pull requests from outside run nothing; four outside-started upstream workflows and `issue-vouch.yml` are deleted and kept deleted. | No code from an outside pull request runs with this repository's runners or tokens. | none | always | [#12](https://github.com/scuttletoby/t3code/pull/12), [#14](https://github.com/scuttletoby/t3code/pull/14), [#23](https://github.com/scuttletoby/t3code/pull/23) | +| A weekly check that the repository's interaction limit never lapses. | Outsiders cannot post while the limit holds. | none | always | [#30](https://github.com/scuttletoby/t3code/pull/30) | +| Secret scan on every push and pull request. | The fork is public: no token or key may land in it. | none | always | [#75](https://github.com/scuttletoby/t3code/pull/75), [#206](https://github.com/scuttletoby/t3code/pull/206), [#207](https://github.com/scuttletoby/t3code/pull/207), [#212](https://github.com/scuttletoby/t3code/pull/212) | +| fork-ci: CI actions any repository can pin (docs-scope, gradle-cache, job-changed, fleet-route, ci-demand, pinned), with their own releases. | Shared CI building blocks, kept general. | none | only where pinned | [#15](https://github.com/scuttletoby/t3code/pull/15), [#16](https://github.com/scuttletoby/t3code/pull/16), [#27](https://github.com/scuttletoby/t3code/pull/27), [#35](https://github.com/scuttletoby/t3code/pull/35), [#55](https://github.com/scuttletoby/t3code/pull/55), [#94](https://github.com/scuttletoby/t3code/pull/94), [#113](https://github.com/scuttletoby/t3code/pull/113), [#141](https://github.com/scuttletoby/t3code/pull/141) | +| fork-ci PR queue: merges armed pull requests in order once their reviews and checks pass. | Merges without someone watching each pull request. | none | only where used | [#18](https://github.com/scuttletoby/t3code/pull/18), [#19](https://github.com/scuttletoby/t3code/pull/19), [#20](https://github.com/scuttletoby/t3code/pull/20), [#21](https://github.com/scuttletoby/t3code/pull/21), [#32](https://github.com/scuttletoby/t3code/pull/32), [#61](https://github.com/scuttletoby/t3code/pull/61), [#70](https://github.com/scuttletoby/t3code/pull/70), [#71](https://github.com/scuttletoby/t3code/pull/71) | +| fork-ci head check and head gate: the queue's required check, posted by a GitHub App and judged by the default branch's code. | A pull request cannot fake its own required check. See [gate trust](docs/fork/gate-trust.md). | none | only where used | [#33](https://github.com/scuttletoby/t3code/pull/33), [#85](https://github.com/scuttletoby/t3code/pull/85), [#87](https://github.com/scuttletoby/t3code/pull/87) | +| Host kits (`fork-kit/`): `gh-apps` (GitHub App tokens for agents), `heavy` (run builds in a capped slice), `golive` (move a boot service to a new build; core and `check` so far), `desk` (a desktop's side of a fleet desk pool). | Things the fork installs on a machine, each with an installer, a self-check and tests. | none | only when installed | [#86](https://github.com/scuttletoby/t3code/pull/86), [#173](https://github.com/scuttletoby/t3code/pull/173), [#182](https://github.com/scuttletoby/t3code/pull/182), [#183](https://github.com/scuttletoby/t3code/pull/183), [#225](https://github.com/scuttletoby/t3code/pull/225) | +| Design notes: host tools (agents on a person's own computer). | Design for review; no code yet. | none | - | [#26](https://github.com/scuttletoby/t3code/pull/26) | ## Adding a line diff --git a/fork-kit/desk/README.md b/fork-kit/desk/README.md index 44577007486c..e2d83beaf5f2 100644 --- a/fork-kit/desk/README.md +++ b/fork-kit/desk/README.md @@ -5,6 +5,17 @@ always-on host over ssh, and the dispatcher there starts one-job runners on this the fleet runbook ([.github/fork-fleet.md](../../.github/fork-fleet.md), "The desktop's side") lists by hand, done by one installer, with a PASS/FAIL check and an uninstall. +## From nothing to a working pool + +1. The project: a desk pool entry in its fleet config ([fork-fleet.md](../../.github/fork-fleet.md), "The desk + link", has a made-up one), released to its protected release branch. +2. The always-on host, once: host step 3 of the runbook ("The fleet files") again, from a main commit that has the + pool entry (it installs the desk link, the seed tool and the key tool); then the desk-link user and its socket + folder, and one dispatcher unit for the pool ("The desk link"). +3. The desktop: the machine file below, then the install (on Windows: [the starter](#windows-wsl2)). +4. The always-on host: add the key install printed, with `fork-fleet-desk-key.py add POOL`. +5. The desktop: `desk-install check` says ALL PASS; the dispatcher's log says the pool's link is up. + ## The machine file The facts of this machine go in the `desk` section of `/etc/fork-kit/machine.json` (root-owned; see