Simplify deployment

README.md

@@ -97,34 +97,52 @@ Edit `User=` and the paths in it if you keep the panel somewhere else.
 
 ## Deploying from Gitea
 
-`.gitea/workflows/deploy.yml` runs the tests on every push to `main`, then
-rsyncs the tree into place, installs anything new from `requirements.txt`,
-restarts the service and waits for the panel to answer again.
+`.gitea/workflows/deploy.yml` fast-forwards the checkout on the server,
+installs anything new from `requirements.txt`, runs the tests, restarts the
+service and waits for the panel to answer again.
 
-It needs a runner **in host mode on the machine that serves the panel**,
-registered with the label `heos` (`runs-on:` must match, or the job queues
-forever), running as the user that owns the directory.
+### Once, by hand on the server
 
-Every step is plain shell. `actions/checkout` is a JavaScript action, and a
-host-mode runner can only run those with `node` on its PATH — swapping the
-clone back for it brings back `Cannot find: node in PATH`. The clone takes
-its URL from the live checkout's own remote, so no URL or token is written
-down here.
-
-Restarting needs one sudoers line:
+The workflow only ever *updates* a checkout. It never creates one, so the
+remote and whatever credentials reach it are set up a single time and stay
+put. As the user the runner runs as:
 
 ```bash
-echo 'franzz ALL=(ALL) NOPASSWD: /usr/bin/systemctl restart heos-panel' \
+git clone <this repo> /var/www/html/heos
+cd /var/www/html/heos
+python3 -m venv .venv
+.venv/bin/pip install -r requirements.txt
+
+sudo cp deploy/heos-panel.service /etc/systemd/system/
+sudo systemctl daemon-reload
+sudo systemctl enable --now heos-panel
+
+echo "$(id -un) ALL=(ALL) NOPASSWD: /usr/bin/systemctl restart heos-panel" \
   | sudo tee /etc/sudoers.d/heos-panel
 sudo chmod 440 /etc/sudoers.d/heos-panel
 ```
 
-The rsync excludes `.venv` and `members.json`, so the runtime and the
-learned stereo-pair membership survive a deploy. It does *not* exclude
-`config.py`: your device names live in git, so commit changes to them
-rather than editing the deployed copy. And since the deploy path is also
-where you edit, `--delete` lands on top of anything uncommitted sitting
-there.
+Edit `User=` and the paths in the unit if the panel lives somewhere else or
+runs as someone else. Until that clone exists the workflow stops on its
+first real step and prints these commands back at you.
+
+### The runner
+
+Host mode, on the machine that serves the panel, registered with the label
+`heos` (`runs-on:` must match, or the job queues forever), running as the
+user that owns the checkout — it writes there, and it fetches with that
+checkout's own git credentials.
+
+Every step is plain shell. `actions/checkout` is a JavaScript action, and a
+host-mode runner can only run those with `node` on its PATH; without one it
+fails with `Cannot find: node in PATH`.
+
+Nothing untracked is disturbed, so `.venv` and `members.json` — the runtime
+and the stereo pair's learned membership — survive a deploy untouched. The
+fast-forward is `--ff-only`, so a tracked file edited on the box without
+being committed stops the deploy rather than being silently overwritten.
+`config.py` is tracked: your device names live in git, so change them there
+and push, rather than editing the deployed copy.
 
 ## Behind a reverse proxy, at /heos