From cd9629643fa165736f58bdfa064edb3b2898f33d Mon Sep 17 00:00:00 2001 From: HomeLab Agent Date: Thu, 5 Nov 2026 03:54:25 -0500 Subject: [PATCH] docs: line up Running as a service and Updating with the shared CLI-contract wording Co-Authored-By: Claude Opus 5.5 --- .../docs/guides/running-as-a-service.md | 348 ++++++++++-------- website/src/content/docs/guides/updating.md | 216 ++++++----- 2 files changed, 308 insertions(+), 256 deletions(-) diff --git a/website/src/content/docs/guides/running-as-a-service.md b/website/src/content/docs/guides/running-as-a-service.md index abd0ec08..bd8336f4 100644 --- a/website/src/content/docs/guides/running-as-a-service.md +++ b/website/src/content/docs/guides/running-as-a-service.md @@ -1,6 +1,6 @@ --- -title: Keeping Paddock running on your laptop -description: Register Paddock as a per-user background service with `paddock service install` — a launchd LaunchAgent on macOS, a systemd --user unit on Linux. +title: Running as a service +description: "`paddock service install` sets Paddock up to start when you log in and to restart if it stops: a LaunchAgent on macOS, a systemd user service on Linux." --- `npx @edspencer/paddock` is a terminal tab. Close the tab, Paddock stops. That is right @@ -12,25 +12,34 @@ npm i -g @edspencer/paddock paddock service install ``` -That registers Paddock as a **per-user background service** — a launchd **LaunchAgent** on -macOS, a **`systemd --user`** unit on Linux — starts it immediately, and starts it again -each time you log in. - -``` -paddock service install register it and start it now -paddock service uninstall stop it and remove the unit -paddock service status is it registered, running, answering; which version -paddock service start start an installed service that is stopped -paddock service stop stop it, and leave it installed -paddock service restart stop it and start it again, re-reading config -paddock service logs the service's log (the last 50 lines; `-f` to follow) -``` +`paddock service install` sets Paddock up to **start when you log in and to restart if it +stops**: a launchd **LaunchAgent** on macOS, a **systemd user service** on Linux. It starts +it straight away too. **Windows isn't supported yet.** To move to a new version, use [`paddock update`](/guides/updating/) — it stops the service, installs, re-writes the unit with the settings this one records, waits for the new version to answer, and puts the old one back if it doesn't. -Install takes a few seconds and says so as it goes: +## Installing + +```bash +paddock service install # 127.0.0.1:7233, data in ~/.paddock +paddock service install --port 7300 # another port +paddock service install --dry-run # print the unit; write nothing +``` + +| Option | What it does | +|---|---| +| `-p, --port ` | the port (default 7233) | +| `--host ` | the bind address (default `127.0.0.1`) | +| `-d, --data-dir ` | a data dir *separate* from your terminal's instance — see below | +| `--verbose` | record the server's own logs, not just warnings | +| `--dry-run` | print the unit it would write, and write nothing | +| `--from-checkout` | install from a git checkout anyway | +| `--refresh` | re-write the unit from the settings the installed one records | +| `--json` | one JSON document on stdout; prose on stderr | + +**It waits until Paddock answers** before it returns: ``` Installing the LaunchAgent and starting Paddock… @@ -40,31 +49,121 @@ Install takes a few seconds and says so as it goes: ✓ Paddock is installed as a launchd LaunchAgent, and running at http://127.0.0.1:7233 ``` -Most of that pause on macOS is the system registering the new LaunchAgent as a login item -— the *"… can run in the background"* notification fires in that window — and it is out of -Paddock's hands. The tick on the last line is not decoration: install **waits for the URL -to answer** before claiming the service is up. If it does not answer within 20 seconds you -get a caveat and a pointer at the logs instead, which is the honest answer when a port -clash has the service restarting in a loop. +The tick on the last line is not decoration. If Paddock does not answer within 20 seconds +you get a caveat and a pointer at the logs instead, and the exit code is **1** — which is +the honest answer when a port clash has the service restarting in a loop. Most of the +pause on macOS is the system registering the new LaunchAgent as a login item (the +*"… can run in the background"* notification fires in that window), and it is out of +Paddock's hands. + +**Running it again is safe:** it keeps the port and settings the service already has — +its port, host, data dir and verbosity — unless you give new ones, and restarts the +running service onto them. `--refresh` does the same and never takes the data dir from +`PADDOCK_DATA_DIR` in your shell; with nothing installed it exits 4 rather than doing a +first install with defaults. It is what `paddock update` runs. + +**`--dry-run` prints the unit and writes nothing** — not the unit, not a folder. The unit +goes to stdout and the line saying where it would go to stderr, so +`paddock service install --dry-run > paddock.service` captures the unit alone. + +It **refuses** to install, with exit 1: + +- **from an npx cache** — the folder is temporary (see below); +- **from a git checkout, unless you add `--from-checkout`** — a unit that runs a working + tree follows every rebuild, branch switch and move of it, at your next login; +- **when something else holds the port** — the service could only crash-loop. A Paddock + on the port is fine: that's the reinstall replacing it. -## Asking it how it is +### Linux: linger + +A systemd user manager starts at your first login and stops at your last logout — so +**without linger, the service stops when you log out**, including out of an SSH session. +`install` and [`doctor`](/guides/updating/#checking-an-install-paddock-doctor) check +(`loginctl show-user $USER -p Linger`) and, if it's off, print: + +```bash +sudo loginctl enable-linger $USER +``` + +**Paddock never runs `sudo` itself**: lingering changes how the machine behaves after you +leave it, and needs a privilege the install otherwise never asks for. If linger is already +on, they say nothing; where the check cannot answer at all (a container with no +`loginctl`), they say nothing either. + +## Where things are + +| | macOS | Linux | +|---|---|---| +| unit | `~/Library/LaunchAgents/net.edspencer.paddock.plist` | `~/.config/systemd/user/paddock.service` | +| log | `~/.paddock/logs/service.log` | `~/.paddock/logs/service.log` | +| working dir | `~/.paddock/service` | `~/.paddock/service` | +| restart | always (`KeepAlive: true`) | always (`Restart=always`) | -`status` answers in prose and in **exit codes**, which is what makes it scriptable: +The unit runs **this Node and this install's `cli.js` by their real paths**, never the +`paddock` shim — so **if you remove that Node version (nvm, fnm, volta), `service status` +and `doctor` warn, and `service install` again fixes it**. The symptom without the warning +is Paddock absent one morning with an *empty* log, because it never got as far as running. -| code | meaning | +A few more details are deliberate: + +**It restarts unconditionally, not only after a crash.** Paddock handles `SIGTERM` by +shutting down cleanly and exiting `0`, so a unit that relaunched only on a *non-zero* exit +stayed down after every routine signal — sleep, logout, a stray `kill` — until the next +login. Neither supervisor restarts a job it was itself asked to stop, so `service stop` and +`service uninstall` still put it down. + +:::caution[Installed before this changed?] +Upgrading the package does not rewrite your unit file, so an older install may still have +the restart-on-crash-only shape. `paddock service status` says so if yours does. Re-run +`paddock service install` to update it. +::: + +**The `PATH` it records is rebuilt, not inherited.** Node's own bin directory first, +then whatever of the installing shell's `PATH` is worth keeping, then the system +directories — dropping the entries that belong to one shell session or one npm +invocation (`fnm_multishells`, `_npx`, `node_modules/.bin`) and any directory that +does not exist. + +**It sets no data dir.** With nothing named, the service and a `paddock` typed into a +terminal both fall through to `~/.paddock` — one instance, two ways to reach it. Pass +`--data-dir` at install time only if you want the service to be a *different* instance. + +**The environment carries `PATH` and nothing else.** A unit file is a readable file in your +home directory, and the value it would be tempting to put in one is a credential. + +## The commands + +| Command | What it does | |---|---| -| `0` | installed, running, and answering on its URL | -| `3` | installed, but not running — or running and not answering | -| `4` | not installed: there is no unit | +| `paddock service install` | write the unit, enable it, start it, and wait until it answers | +| `paddock service uninstall` | **stop it and remove the unit. Your data and logs stay.** | +| `paddock service start` | start the installed service, and wait until it answers | +| `paddock service stop` | **stop it until `service start`, or the next login or boot** | +| `paddock service restart` | stop it and start it again, re-reading the unit and config | +| `paddock service status [--json]` | installed? running? answering? which version? | +| `paddock service logs [-f] [-n ]` | **the last 50 lines; `-f` follows, `-n` sets how many** | + +`stop` **doesn't disable the service. To keep it off for good, use `service uninstall`.** +That is the service managers' own convention: `systemctl --user stop` and a launchd +`bootout` both leave the unit to come back at the next login. -Those are the numbers `systemctl status` and LSB init scripts already use, so an -Ansible task or a shell `if` written against either keeps working. "Not answering" -counts as not running on purpose: both supervisors report a service that is -crash-looping on a port clash as `running` for most of the window between -restarts, and a Paddock nothing can reach is not up whatever launchd thinks. +`start` clears a failed state first on Linux (`systemctl --user reset-failed`): a unit that +hit systemd's limit of five starts in ten seconds stays failed, with nothing in the log +about why, until something does. -`--json` carries the same report as one document on stdout, with the **installed** -and **running** versions in it: +`install`, `uninstall`, `start`, `stop` and `restart` take **`--json`** too: one document on +stdout — `ok`, `action`, an `error` when it failed, and the same fields as +`status --json`, as they are afterwards — and every word of prose on stderr. + +### Asking it how it is + +`status` answers in prose and in **exit codes**, which is what makes it scriptable (see +[Exit codes](#exit-codes)). "Not answering" counts as not running on purpose: both +supervisors report a service that is crash-looping on a port clash as `running` for most +of the window between restarts. + +`--json` carries the same report as one document on stdout, with the **installed** and +**running** versions in it: ```bash paddock service status --json @@ -85,66 +184,73 @@ paddock service status --json } ``` -Two versions, because they can differ and the difference is invisible otherwise: -that is an instance upgraded with `npm i -g` under a service that has not -restarted. `paddock service restart` is the fix, and `status` says so. - -`status` also warns when the **Node the unit names has gone** — which is what nvm, -fnm and volta do the moment you remove a version. The symptom without the warning -is Paddock being absent one morning with an *empty* log, because it never got as -far as running. +Two versions, because they can differ and the difference is invisible otherwise: that is +an instance upgraded with `npm i -g` under a service that has not restarted. +`paddock service restart` is the fix, and `status` says so. For everything around the service as well — the Node it runs, the port, linger, the data dir, your Claude login, a newer version — run `paddock doctor` ([Checking an install](/guides/updating/#checking-an-install-paddock-doctor)). -## Reading the logs +## Busy -```bash -paddock service logs # the last 50 lines -paddock service logs -n 200 # more of them -paddock service logs -f # and keep printing -``` +**`service stop` and `service restart` first ask the running Paddock whether it's busy** — +a chat turn running, a background task a live session still holds, or a scheduled job. +**If it is, they refuse with exit 75 and say what's running. Wait and try again, or add +`--force`, which prints the same message prefixed `Overriding:` and goes ahead.** -One file, on every OS: `~/.paddock/logs/service.log`, written by the supervisor -itself from both the service's stdout and its stderr. Paddock **rotates it**, at -8 MB, keeping `service.log.1` … `.3` beside it — nothing else would, because a -`systemd --user` unit writing to a file gets no journal rotation and macOS has -never had anything that would. +``` +paddock: Paddock is busy: 1 chat turn is running. Run it from a terminal, not from inside + a Paddock chat. +``` -Linux used to send this to the journal. It does not any more, for three reasons: -`journalctl --user` shows *nothing* on a distribution whose journal is volatile — -which is exactly the reboot you are asking about; it made "where are the logs" -have a different answer on each platform; and it ruled out Windows, which nothing -built here may do. +Being refused is the useful case: a restart kills a chat turn mid-sentence, and the turn +cannot be resumed from where it was. `uninstall` doesn't ask — removing the service is an +explicit act — and neither does `start`, which has nothing to cut short. -`uninstall` keeps the logs. The last thing anyone wants from an uninstall is for -the record of *why* they are uninstalling to vanish with it. +`paddock busy` asks the same question on its own: **0** not busy, **75** busy, **3** +nothing running. -## Stopping and restarting +:::caution[Run it from a terminal, not from a chat] +Paddock's agents can drive Paddock. A chat that runs `paddock service restart` is itself one +of the chat turns the busy check counts, so it always sees itself as busy — and `--force` +from there stops the service running that chat, which then never gets to say so. +::: -`restart` is the one you will actually reach for — after editing -`paddock.config.yaml`, or to recover a service that stopped. It re-reads the unit on -the way up, and it does not care whether Paddock was running when you asked. +## Logs ```bash -paddock service restart -``` +paddock service logs # the last 50 lines +paddock service logs -n 200 # more of them +paddock service logs -f # and keep printing ``` - Restarting Paddock… - ✓ Paddock is running (pid 41022) at http://127.0.0.1:7233 -``` +One file, `~/.paddock/logs/service.log`, which stdout and stderr both append to, on every +OS. **Paddock rotates it itself** (by copying and truncating, at 8 MB, keeping three +older generations, `service.log.1` … `.3`), because the service manager holds it open — +and nothing else would: a systemd user unit writing to a file gets no journal rotation, +and macOS has never had anything that would. + +Linux used to send this to the journal. It does not any more: `journalctl --user` shows +*nothing* on a distribution whose journal is volatile — which is exactly the reboot you are +asking about — and one file means one answer to "where are the logs" everywhere. -`start` and `restart` **wait for the URL to answer** before printing that line. Neither -launchd nor systemd knows whether the port came up — they know a process was forked, and -they will report a service that is crash-looping on a port clash as `running` for most of -the window between restarts. If the URL does not answer within 20 seconds you get a -caveat and a pointer at the logs instead of a tick. +`uninstall` keeps the logs. The last thing anyone wants from an uninstall is for the record +of *why* they are uninstalling to vanish with it. -`stop` is a stop, not an uninstall: the unit stays registered, `status` still finds it, -and it comes back at your next login — or immediately with `paddock service start`. -Use `uninstall` when you want it gone for good. +## Exit codes + +| Code | Meaning | +|---|---| +| 0 | running and answering (`status`), or done | +| 1 | failed — including an install or start that never answered, and the refusals above | +| 2 | usage: an unknown action or flag, or a bad value | +| 3 | **installed but not running or not answering** | +| 4 | **not installed**: there is no unit (`status`, `start`, `stop`, `restart`, `logs`) | +| 75 | **busy**: `stop` or `restart` refused, and why was printed. Wait, or `--force` | + +Codes 3 and 4 are the numbers `systemctl status` and LSB init scripts already use, so an +Ansible task or a shell `if` written against either keeps working. ## At login, not at boot @@ -165,80 +271,8 @@ out of how your Claude login works: A boot-time instance is a different thing, and you can have it — but the price is explicit: a system-level unit with `claude.credentials: own` and a long-lived `CLAUDE_CODE_OAUTH_TOKEN` sitting in its environment. That is the -[server story](/guides/deploying/), not this one. - -### Linux: you also need lingering - -A `systemd --user` manager starts at your first login and stops at your last logout — so -by default the unit dies when you log out, including out of an SSH session. To keep it up: - -```bash -loginctl enable-linger $USER -``` - -`paddock service install` prints this rather than running it: lingering changes how the -machine behaves after you leave it, and needs a privilege the install otherwise never -asks for. - -It also **checks** — `loginctl show-user $USER -p Linger` — and says nothing if you -have already enabled it. Printing the instruction at everybody, every time, is how -the one line that matters to the people who have *not* became indistinguishable from -boilerplate. Where the check cannot answer at all (a container with no `loginctl`), -it says nothing either: handing someone a command their machine does not have is -worse than silence. - -## What gets written - -Exactly one file, plus a directory for logs. Nothing else on your machine changes. - -| | macOS | Linux | -|---|---|---| -| unit | `~/Library/LaunchAgents/net.edspencer.paddock.plist` | `~/.config/systemd/user/paddock.service` | -| logs | `~/.paddock/logs/service.log` | `~/.paddock/logs/service.log` | -| working dir | `~/.paddock/service` | `~/.paddock/service` | -| restart | always (`KeepAlive: true`) | always (`Restart=always`) | - -Five details in there are deliberate and worth knowing about: - -**It restarts unconditionally, not only after a crash.** Both units used to relaunch -Paddock only on a *non-zero* exit, which sounds like the polite choice and is, for a -service, a trap: Paddock handles `SIGTERM` by shutting down cleanly and exiting `0`, so -every routine signal the OS sends — sleep, logout, a stray `kill` — looked like "it meant -to stop", and Paddock stayed down until the next login. A crash was the survivable case. -Unconditional restart does not make the service unstoppable, because neither supervisor -restarts a job it was itself asked to stop: `paddock service uninstall` still puts it -down in one command. Intent belongs in a command, not in an exit code. - -:::caution[Installed before this changed?] -Upgrading the package does not rewrite your unit file, so an older install still has the -restart-on-crash-only shape. `paddock service status` says so if yours does. Re-run -`paddock service install` to update it. -::: - -**It invokes `node` by absolute path, with the script path after it** — not the `paddock` -bin. The bin is an npm symlink with a `#!/usr/bin/env node` shebang, and launchd hands a -process a stub `PATH` that a version manager's `node` is not on. Exec'ing the bin directly -would fail at login with a bare "no such file or directory". The path is also -**resolved through symlinks first**: under fnm, `process.execPath` is a link into a -per-terminal directory that is deleted when that terminal exits, so a unit naming it -would work until you closed the tab. - -**The `PATH` it records is rebuilt, not inherited.** Node's own bin directory first, -then whatever of the installing shell's `PATH` is worth keeping, then the system -directories — dropping the entries that belong to one shell session or one npm -invocation (`fnm_multishells`, `_npx`, `node_modules/.bin`) and any directory that -does not exist. A unit that inherited the whole of one terminal's `PATH` is a unit -whose `git` goes missing at some later login, with the symptom appearing inside an -agent's turn. - -**It sets no data dir.** With nothing named, the service and a `paddock` typed into a -terminal both fall through to `~/.paddock` — one instance, two ways to reach it. Pass -`--data-dir` at install time only if you actively want the service to be a *different* -instance from your terminal one. - -**The environment carries `PATH` and nothing else.** A unit file is a readable file in your -home directory, and the value it would be tempting to put in one is a credential — which is -precisely what the user-agent shape exists to avoid needing. +[server story](/guides/deploying/), not this one. (On Linux, linger is what lets a user +service start at boot: see [above](#linux-linger).) ## Installing from npx: it refuses @@ -252,7 +286,8 @@ paddock: `service install` needs an install path that will still be there at you npx materialises the package under `~/.npm/_npx//`. Those copies accumulate, and the whole tree is prunable. A unit pointing in there works right up until it doesn't — at some -future login, unattended. Refusing beats writing a unit we know will rot. +future login, unattended. A git checkout is refused for the same kind of reason, and +`--from-checkout` is there for working on Paddock itself. ## Access, once it is always on @@ -282,7 +317,7 @@ the fix belongs in the generated plist. ## Windows -Not supported. Windows has no per-user service concept that maps onto either of these +Not supported yet. Windows has no per-user service concept that maps onto either of these without a scheduled task or a service wrapper, and shipping an untested third writer would be worse than saying so. `paddock service` tells you as much rather than guessing. @@ -299,3 +334,8 @@ cosmetic: | credentials | token in the unit's environment | your own Claude login | | exposure | behind auth at a reverse proxy | loopback only | | provisioning | Ansible, infra-as-code | one command | + +## Next + +[Updating](/guides/updating/): `paddock update`, and what it does when the new version +doesn't start. diff --git a/website/src/content/docs/guides/updating.md b/website/src/content/docs/guides/updating.md index 8a3b4cce..34d3a497 100644 --- a/website/src/content/docs/guides/updating.md +++ b/website/src/content/docs/guides/updating.md @@ -1,5 +1,5 @@ --- -title: Updating Paddock +title: Updating description: "`paddock update` installs the new version, refreshes the service unit, waits for it to answer — and puts the old version back if it doesn't." --- @@ -7,10 +7,10 @@ description: "`paddock update` installs the new version, refreshes the service u paddock update ``` -That is the whole thing. It asks npm what the latest version is, asks you to confirm, -stops your service, installs, starts it again on the new version, and waits until -`/api/health` reports the version it just installed. If that never happens, it reinstalls -the version you were on and tells you so. +That is the whole thing. **It asks the registry for the latest version, checks whether +Paddock is busy, asks you to confirm, downloads the new version first (while the old one is +still running), stops the service, installs, starts the new version and waits until it +answers.** If anything from the install on fails, it puts the old version back. ``` Paddock 0.82.0 is available (you have 0.81.0). @@ -18,102 +18,100 @@ Paddock 0.82.0 is available (you have 0.81.0). Changes: https://github.com/edspencer/paddock/releases/tag/v0.82.0 ``` -## Look before you leap +## Options -`paddock update --check` asks the registry, prints what it found, and changes nothing. It -exits **0** whether or not there is an update — a script reads `updateAvailable` from the -JSON rather than the exit code: +| Option | What it does | +|---|---| +| `--check` | **reports and changes nothing. It exits 0 whether or not there's an update; with `--json`, read `updateAvailable`.** | +| `--to ` | **a version or a dist-tag (`next`). It's the only way to move to a lower version.** | +| `--yes`, `-y` | **skips the question. Without a terminal (a script, cron), `--yes` is required, or `update` exits 2.** | +| `--force` | **skips the busy check, and nothing else: the health check and the rollback still run.** | +| `--json` | one JSON document on stdout; prose on stderr | ```bash paddock update --check --json | jq '.updateAvailable, .target' +paddock update --to 0.81.0 # a version — the only way to go BACK +paddock update --to next # a dist-tag +paddock update --yes # from a script ``` -What it found is cached in `/update-check.json`, and `paddock service status` -repeats it. **Nothing in Paddock contacts the registry on its own** — not the server, not -at startup, not in the background. Only `update`, `update --check` and `doctor` ask, and -only when you run them. +`update` never goes backwards by accident: a registry whose `latest` is *older* than what +you have is reported and ignored, and a `latest` that points at a prerelease is not +installed unless `--to` names it. -## Updating while something is running +## Busy -`update` asks the running instance whether it is busy before it stops anything, and -refuses if it is: +**If Paddock is busy, `update` refuses with exit 75 before anything is stopped**, and says +what's running. Wait, or use `--force`. ``` paddock: Paddock is busy: 2 chat turns are running. Run it from a terminal, not from inside a Paddock chat. ``` -A chat turn is a live `claude` subprocess writing a transcript, and it cannot be resumed -from where it was interrupted — so a restart loses it. Wait, or override the check with -`--force`. `--force` skips **only** that check: the health check and the rollback still run. +Busy means a chat turn running, a background task a live session still holds, or a +scheduled job. A chat turn is a live `claude` subprocess writing a transcript, and it +cannot be resumed from where it was interrupted — so a restart loses it. -:::caution[Run it from a terminal, not from a chat] -Paddock's agents can drive Paddock. A keeper chat that runs `paddock update` is itself one -of the chat turns the busy check counts, so it will always see itself as busy — and -`--force` from there stops the service that is running the chat, which then never gets to -tell you what happened. This is why the refusal says where to run it from. +:::caution[Run it from a terminal, not from inside Paddock] +Paddock's agents can drive Paddock. A chat that runs `paddock update` is itself one of the +things the busy check counts, so it will always see itself as busy — and stopping the +service ends the chat, which then never gets to tell you what happened. This is why the +refusal says where to run it from. ::: -## Going somewhere particular - -```bash -paddock update --to 0.81.0 # a version — the only way to go BACK -paddock update --to next # a dist-tag -``` - -`update` never goes backwards by accident: a registry whose `latest` is *older* than what -you have is reported and ignored, and a `latest` that points at a prerelease is not -installed unless `--to` names it. - -## Without a terminal +## If the new version doesn't start -`update` asks a question, and a question needs a terminal. In a script, a cron job or an -Ansible task there is none, so it exits **2** and says `--yes` is required rather than -guessing: +**`update` waits up to 30 seconds for the new version to answer. If it doesn't, it prints +the last 20 lines of the log, reinstalls the old version and checks that it answers: +exit 6, "0.82.0 didn't start; 0.81.0 is running again." If the old version doesn't come +back either, it exits 7 and prints the commands to run by hand.** -```bash -paddock update --yes -``` +It waits for `/api/health` to report the version it installed — not merely for the URL to +answer, because the old server, a sibling instance and a supervisor that restarted the old +unit all answer too. -## When it goes wrong +## Without a service -The exit code is the whole report, and the two failure codes mean different things: - -| Code | What happened | What you do | -|---|---|---| -| 0 | Updated, or already up to date | nothing | -| 2 | No terminal to ask, so `--yes` is required | add `--yes` | -| 5 | This install can't update itself — the right command was printed | run that command | -| 6 | The new version didn't start. **The old one is running again** | read the log it printed, then report it | -| 7 | The new version didn't start **and the old one could not be restored** | run the commands it printed | -| 75 | Busy | wait, or `--force` | - -On a rollback, `update` prints the last 20 lines of the service log before it puts the old -version back — which is usually enough to see why the new one did not come up. +If you run `paddock serve` yourself, there is no service to stop. With nothing running, +`update` installs the new version and you **restart Paddock to use it**. If a foreground +`serve` is answering, `update` asks you to stop it first (Ctrl-C in its terminal) and +exits 3, rather than replacing files under a running server; run it again once it's +stopped. ## Installs that can't update themselves (exit 5) -Paddock works out where it is running from, and five layouts are not its to replace. Each -prints the command that *would* work: +Paddock works out how it was installed, and some installs aren't its to replace. Those +exit 5 and print the right command instead: -| Where it is running from | What it tells you | +| How it was installed | What it tells you | |---|---| -| A container image | `docker compose pull && docker compose up -d` | -| A managed install (`PADDOCK_UPDATE_HINT` is set) | whatever that variable says | -| `npx` / `pnpm dlx` | `npx @edspencer/paddock@latest` — npx already runs the latest each time | -| A checkout | `git pull && npm install && npm run build` | -| A dependency of another project | update it in that project | +| Docker (`PADDOCK_IN_DOCKER=1`, set by the image) | `docker compose pull && docker compose up -d`, with the image tag | +| A managed install (`PADDOCK_UPDATE_HINT` is set) | the hint | +| `npx` / `pnpm dlx` | **`npx @edspencer/paddock@latest` already runs the latest** | +| A git checkout | `git pull && npm install && npm run build` | +| A global folder you can't write to | **the same command with `sudo`. Paddock never runs `sudo` itself.** | +| yarn global, or a dependency of another project | update it the way you installed it | A global **npm**, **pnpm**, **bun** or **volta** install updates in place. -If the global folder is not writable, `update` prints the same command with `sudo` and -exits 5. **It never runs `sudo` itself** — that is a decision for the person at the -keyboard, not for a tool that has just decided to replace its own files. +**A managed install: if `PADDOCK_UPDATE_HINT` is set, `update` prints it and exits 5.** Set +it in the environment of an install something else manages — an Ansible role, a NixOS +module, a deploy job — so nobody updates it by hand: + +```bash +docker run -e PADDOCK_UPDATE_HINT='ansible-playbook -i prod paddock.yml' … +``` + +## Docker and Watchtower -## In Docker +```bash +docker compose pull && docker compose up -d +``` -Nothing installs anything inside a container. The image sets `PADDOCK_IN_DOCKER=1`, so -`update` there prints the image to pull and exits 5: +**Nothing installs anything inside a container.** The image sets `PADDOCK_IN_DOCKER=1`, +so `update` there prints the image to pull and exits 5. `paddock` is on `PATH` in the +image, so you can ask a running container: ```bash docker exec paddock paddock update --check @@ -124,44 +122,35 @@ Paddock 0.82.0 is available (you have 0.81.0). Run: docker compose pull && docker compose up -d (image ghcr.io/edspencer/paddock:0.82.0) ``` -`paddock` is on `PATH` in the image, so `docker exec paddock paddock busy` works too — -which is what lets an automatic updater wait for a quiet moment. See -[Deploying Paddock](/guides/deploying/#keeping-it-current). +**Watchtower:** enable lifecycle hooks (`WATCHTOWER_LIFECYCLE_HOOKS=true`) and label the +container `com.centurylinklabs.watchtower.lifecycle.pre-update=paddock busy`. **When +Paddock is busy the hook exits 75 and Watchtower skips the update until its next run.** +[Deploying Paddock](/guides/deploying/#keeping-it-current) has the full Compose file, and +the same wait as an Ansible task. -If something else manages the container — Ansible, a Helm chart, a deploy job — set -`PADDOCK_UPDATE_HINT` to the command that actually upgrades it, and `update` prints that -instead of guessing: +## No automatic checks -```bash -docker run -e PADDOCK_UPDATE_HINT='ansible-playbook -i prod paddock.yml' … -``` - -## What it does, step by step - -Worth knowing if you are automating around it, or if it stops half way: - -1. takes `/update.lock`, so two updates cannot interleave; -2. works out how this copy was installed; -3. asks the registry for the target version and its `engines.node`; -4. compares — and stops here with `--check`; -5. checks the global folder is writable; -6. asks the running instance whether it is **busy**, before anything is stopped; -7. asks you, unless `--yes`; -8. fetches **both** the new and the current version into the npm cache, while the old - version is still serving, so a rollback has its package to hand even if the network - has gone; -9. stops the service; -10. installs with the package manager this copy came from; -11. hands over to the **new** CLI, which re-writes the service unit in its own format - with the port and data dir the old one recorded (`paddock service install --refresh`); -12. waits for `/api/health` to report the version it installed — not merely for the URL - to answer, because the old server, a sibling instance and a supervisor that restarted - the old unit all answer too; -13. and if any of 10–12 fails, puts the old version back. +**Paddock never checks for updates by itself. Only `update`, `update --check` and `doctor` +ask the registry, and only when you run them. `service status` repeats what the last of +those found.** Not the server, not at startup, not in the background. What the last check +found is cached in `/update-check.json`. The registry it asks is `npm_config_registry`, else `npm config get registry`, else `https://registry.npmjs.org`. +## Exit codes + +| Code | What happened | What you do | +|---|---|---| +| 0 | Updated, or up to date (or `--check` reported) | nothing | +| 1 | Failed, before anything was stopped | read the message | +| 2 | Usage, or no terminal without `--yes` | fix the command, or add `--yes` | +| 3 | A foreground `serve` is still answering | stop it, then run `update` again | +| 5 | **This install can't update itself; the right command was printed** | run that command | +| 6 | **The update failed and was rolled back; the old version is running again** | read the log it printed, then report it | +| 7 | **The update failed and couldn't be rolled back; a person is needed** | run the commands it printed | +| 75 | **Busy** | wait, or `--force` | + ## Checking an install: `paddock doctor` `paddock doctor` runs every check an update depends on, and a few Paddock needs to work at @@ -197,6 +186,27 @@ update check, the only one that leaves the machine. Like `update --check`, that writes what it found to `/update-check.json`, so `paddock service status` repeats it. +## What it does, step by step + +Worth knowing if you are automating around it, or if it stops half way: + +1. takes `/update.lock`, so two updates cannot interleave; +2. works out how this copy was installed; +3. asks the registry for the target version and its `engines.node`; +4. compares — and stops here with `--check`; +5. checks the global folder is writable; +6. asks the running instance whether it is **busy**, before anything is stopped; +7. asks you, unless `--yes`; +8. fetches **both** the new and the current version into the npm cache, while the old + version is still serving, so a rollback has its package to hand even if the network + has gone; +9. stops the service; +10. installs with the package manager this copy came from; +11. hands over to the **new** CLI, which re-writes the service unit in its own format + with the port and data dir the old one recorded (`paddock service install --refresh`); +12. waits for `/api/health` to report the version it installed; +13. and if any of 10–12 fails, puts the old version back. + ## Updating by hand There is nothing magic about `update` — it runs the commands you would: @@ -213,3 +223,5 @@ paddock service status what the **existing** one records, rather than from the flags and environment of the shell you happen to be in. With nothing installed it exits 4 rather than quietly performing a first install with defaults. + +See also [Running as a service](/guides/running-as-a-service/).