From b120ef2e0e2b96c881ec654cace505328d986a32 Mon Sep 17 00:00:00 2001 From: S Date: Sun, 1 Mar 2026 08:28:46 -0500 Subject: [PATCH] docs: add details about native runner boot mode and sudo requirements --- README.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 5a69823..2099ca6 100644 --- a/README.md +++ b/README.md @@ -112,7 +112,7 @@ All scripts run from the MacBook and SSH into remotes. This means: ### Why Docker Compose for Gitea but native binary for macOS runner? -Docker Desktop on macOS is heavyweight (~4 GB), requires a commercial license for organizations, and is unreliable for long-running background services (it suspends when the Mac sleeps). A native `act_runner` binary with a launchd plist is 30 MB, starts on login, and survives sleep/wake cycles. On Linux, Docker is the native container runtime with no overhead, so Docker Compose is the obvious choice there. +Docker Desktop on macOS is heavyweight (~4 GB), requires a commercial license for organizations, and is unreliable for long-running background services (it suspends when the Mac sleeps). A native `act_runner` binary with a launchd plist is 30 MB, survives sleep/wake cycles, and by default starts at login via `~/Library/LaunchAgents/`. For headless Macs or dedicated CI machines, set `boot = true` in `runners.conf` to install the plist to `/Library/LaunchDaemons/` instead — this starts the runner at boot before any user logs in (requires `sudo` for plist installation and `launchctl` load/unload). On Linux, Docker is the native container runtime with no overhead, so Docker Compose is the obvious choice there. ### Why `envsubst` templates instead of Jinja2/Helm/gomplate? @@ -190,6 +190,10 @@ Phases run strictly sequentially. Phase 4 could potentially import all 3 repos i Runner containers get `/var/run/docker.sock` mounted, giving them root-equivalent access to the host's Docker daemon. This is required for runners to spawn job containers but is a security concern for untrusted code. For a private instance with trusted users, this is the standard Gitea runner deployment. +### Native runner `boot` mode requires sudo + +When `boot = true` is set in `runners.conf`, `manage_runner.sh` uses `sudo` for three operations: copying the plist to `/Library/LaunchDaemons/`, loading/unloading the service via `launchctl`, and removing the plist on teardown. The plist includes a `UserName` entry so the daemon process runs as the deploying user, not root. The newsyslog config (log rotation) always requires `sudo` regardless of boot mode, since it installs to `/etc/newsyslog.d/`. + ### Backup archives are unencrypted `gitea dump` produces a zip file containing the database, all repos, and config. This is transferred over SSH (encrypted in transit) and stored on Fedora's filesystem. At-rest encryption is the user's responsibility (e.g., LUKS on the Fedora backup volume).