diff --git a/README.md b/README.md index 8a6e713..3a84eac 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,8 @@ The proxy itself is not written yet; this repo holds the stack around it so far. and `logs` drive the stack's OpenRC user services. Every other subcommand (`serve`, `web`, `tui`, `check`, ...) goes to prain's own CLI in `PRAIN_ROOT/.venv`, with `scripts/env.sh` sourced first, so you no longer need to source it yourself. (In a shell where you did, the -venv's `prain` comes first on PATH and `prain up` is unknown there.) +venv's `prain` comes first on PATH and `prain up` is unknown there.) `prain --help` shows +prain's own help with the stack commands merged into its command list. prain up [NAME...] start the services (all by default), waiting until each is ready prain down [NAME...] stop them, in reverse order @@ -18,14 +19,22 @@ venv's `prain` comes first on PATH and `prain up` is unknown there.) prain logs [NAME...] tail -F their logs (~/.local/state/prain/NAME.log) Services live in `~/.config/prain/prain.conf` (`PRAIN_CONF` overrides): `PRAIN_SERVICES` -lists them, and per service `cmd_NAME` (the command, run in `PRAIN_ROOT` with env.sh -sourced), `ready_NAME` (a URL `prain up` waits for) and `need_NAME` (dependencies). See -`scripts/prain.conf.example`. +lists them. Per service: +- `cmd_NAME`: the command, run in `PRAIN_ROOT` with env.sh sourced. +- `ready_NAME`: a URL `prain up` waits for. +- `requires_NAME`: services that must already be up. If one isn't, NAME refuses to start + with a message (`prain: web needs vllm, which is not running ... Start it first: prain up + vllm`). It never starts them itself. + +See `scripts/prain.conf.example`. One OpenRC script, `openrc/init.d/prain`, serves them all through links named `prain.NAME`. -OpenRC's supervise-daemon restarts a crashed service. It gives up after more than -`respawn_max` (3) crashes within `respawn_period` seconds (600; 1800 for vLLM in -`openrc/conf.d/prain.vllm`), so crashes further apart are restarted forever. +OpenRC settings go in `~/.config/rc/conf.d/prain.NAME`: +- `rc_after="prain.vllm"`: start order when both are in a runlevel. It doesn't start vLLM. +- `respawn_max` (3) and `respawn_period` (600 s; 1800 for vLLM): supervise-daemon restarts + a crashed service, and gives up after more than `respawn_max` crashes within + `respawn_period`. Crashes further apart are restarted forever. +- `respawn_delay` (5 s). ### Install @@ -34,8 +43,9 @@ OpenRC's supervise-daemon restarts a crashed service. It gives up after more tha cp scripts/prain.conf.example ~/.config/prain/prain.conf ln -s "$PWD/openrc/init.d/prain" ~/.config/rc/init.d/prain for n in vllm web; do ln -s prain ~/.config/rc/init.d/prain.$n; done - cp openrc/conf.d/prain.vllm ~/.config/rc/conf.d/ - rc-update --user add prain.web default # optional: start with the session (pulls in vllm) + cp openrc/conf.d/prain.* ~/.config/rc/conf.d/ + # optional, start both with the session (web waits for vLLM through rc_after): + rc-update --user add prain.vllm default && rc-update --user add prain.web default A new service is a `cmd_NAME` line, its name in `PRAIN_SERVICES` and one more `prain.NAME` link. diff --git a/openrc/conf.d/prain.web b/openrc/conf.d/prain.web new file mode 100644 index 0000000..d42be1c --- /dev/null +++ b/openrc/conf.d/prain.web @@ -0,0 +1,3 @@ +# Order only: in a runlevel with both, web starts after vLLM is ready. Starting web alone +# never starts vLLM; requires_web in prain.conf makes it fail with a message instead. +rc_after="prain.vllm" diff --git a/openrc/init.d/prain b/openrc/init.d/prain index a316b76..c771ab5 100755 --- a/openrc/init.d/prain +++ b/openrc/init.d/prain @@ -1,7 +1,8 @@ #!/sbin/openrc-run # One service of the prain stack, picked by the link name: prain.vllm, prain.web, ... -# What it runs comes from prain.conf (`prain run NAME`); supervision settings from -# conf.d/prain.NAME (respawn_max, respawn_period, respawn_delay). +# What it runs and what must already run come from prain.conf (`prain run NAME`, +# `prain deps NAME`); supervision settings and start order from conf.d/prain.NAME +# (respawn_max, respawn_period, respawn_delay, rc_after). stack_name=${RC_SVCNAME#prain.} description="prain stack: ${stack_name}" @@ -14,16 +15,13 @@ respawn_period=${respawn_period:-600} output_log=${XDG_STATE_HOME:-$HOME/.local/state}/prain/${stack_name}.log error_log=${output_log} -depend() { - need $("${prain_bin:-$HOME/.local/bin/prain}" need "${RC_SVCNAME#prain.}") -} - start_pre() { if [ "${RC_SVCNAME}" = prain ]; then eerror "Start a link to this script, like prain.vllm" return 1 fi checkpath -d "${output_log%/*}" + "${command}" deps "${stack_name}" # requires_NAME in prain.conf: refuse, never start them } start_post() { diff --git a/scripts/prain b/scripts/prain index 22cc92c..c6be6ab 100755 --- a/scripts/prain +++ b/scripts/prain @@ -1,6 +1,6 @@ #!/bin/bash # prain front door. up, down, restart, status and logs drive the stack's OpenRC user -# services (prain.NAME); run, need and wait are what those services call. Anything else +# services (prain.NAME); run, deps and wait are what those services call. Anything else # goes to prain's own CLI in PRAIN_ROOT/.venv, with its scripts/env.sh sourced. set -euo pipefail @@ -50,9 +50,18 @@ run) prain_env eval "exec ${cmd//$'\n'/ }" ;; -need) - get need "$2" - echo +deps) # fail, without starting anything, unless the services NAME requires are up + for d in $(get requires "$2"); do + url=$(get ready "$d") + if [ -n "$url" ]; then + curl -sf -o /dev/null "$url" && continue + else + rc-service --user "prain.$d" status > /dev/null 2>&1 && continue + fi + echo "prain: $2 needs $d, which is not running${url:+ (no answer from $url)}." \ + "Start it first: prain up $d" >&2 + exit 1 + done ;; wait) url=$(get ready "$2") @@ -64,10 +73,19 @@ wait) sleep 2 done ;; -'' | -h | --help) - echo "stack: prain up|down|restart|status|logs [NAME...] (services: ${services[*]})" +'' | -h | --help) # prain's own help, with the stack commands merged into its list prain_env - exec "$PRAIN_ROOT/.venv/bin/prain" --help + "$PRAIN_ROOT/.venv/bin/prain" --help | awk -v stack="$(cat <<-EOF + up [NAME...] start services (all: ${services[*]}), each waits until ready + down [NAME...] stop services, in reverse order + restart [NAME...] restart services + status [NAME...] show whether services run + logs [NAME...] follow service logs ($logdir/NAME.log) + EOF + )" ' + /^(usage: prain| )[^{]*\{/ { sub(/\{/, "{up,down,restart,status,logs,") } + { print } + /^ \{/ { print stack }' ;; *) prain_env diff --git a/scripts/prain.conf.example b/scripts/prain.conf.example index e36a8b7..aabb765 100644 --- a/scripts/prain.conf.example +++ b/scripts/prain.conf.example @@ -7,8 +7,9 @@ PRAIN_ROOT=/home/fabian/coding/misc/prain PRAIN_SERVICES="vllm web" # `prain up` starts in this order, `prain down` stops in reverse # cmd_NAME: what service prain.NAME runs. ready_NAME: URL that answers once it can serve -# (`prain up` waits for it, PRAIN_READY_TIMEOUT seconds, default 900). need_NAME: services -# it depends on (OpenRC starts them first and stops it with them). +# (`prain up` waits for it, PRAIN_READY_TIMEOUT seconds, default 900). requires_NAME: +# services that must already be up (their ready URL answers); if not, NAME refuses to start +# and says so. They are never started for it. cmd_vllm='prain serve build/agent-int4.toml models/gemma-4-26B-A4B-it-Uncensored-MAX -- --served-model-name gemma4 --language-model-only --max-model-len 16384 --max-num-batched-tokens 1024 --enable-prefix-caching --port 8000 @@ -16,4 +17,4 @@ cmd_vllm='prain serve build/agent-int4.toml models/gemma-4-26B-A4B-it-Uncensored ready_vllm=http://127.0.0.1:8000/health cmd_web='prain web --host 0.0.0.0 --port 8080 --url http://127.0.0.1:8000 --config build/agent-int4.toml' -need_web=vllm +requires_web=vllm diff --git a/scripts/test_prain.sh b/scripts/test_prain.sh index fdd3ad3..e14575c 100755 --- a/scripts/test_prain.sh +++ b/scripts/test_prain.sh @@ -10,7 +10,15 @@ cat > "$t/root/scripts/env.sh" < "$t/root/.venv/bin/prain" +cat > "$t/root/.venv/bin/prain" <<'EOF' +#!/bin/sh +if [ "$1" = --help ]; then + printf 'usage: prain [-h] {check,web} ...\n\npositional arguments:\n {check,web}\n' + printf ' check validate\n' + exit 0 +fi +echo "prain $* env=$FROM_ENV_SH cwd=$PWD" +EOF printf '#!/bin/sh\necho "$*"\n' > "$t/bin/rc-service" chmod +x "$t/root/.venv/bin/prain" "$t/bin/rc-service" cat > "$t/prain.conf" </dev/null; echo $?)" -check need "a" "$("$p" need b)" -check need-none "" "$("$p" need a)" check wait-without-url 0 "$("$p" wait a; echo $?)" check wait-times-out 1 "$("$p" wait b 2>/dev/null; echo $?)" check up-in-order "--user prain.a start @@ -41,4 +49,17 @@ check up-in-order "--user prain.a start check down-in-reverse "--user prain.b stop --user prain.a stop" "$("$p" down)" check status-one "--user prain.b status" "$("$p" status b)" +check deps-ok-when-running 0 "$("$p" deps b; echo $?)" +check deps-fail-without-starting-them "prain: x needs b, which is not running (no answer from http://127.0.0.1:9/never). Start it first: prain up b +1" "$("$p" deps x 2>&1; echo $?)" +check help-merges-stack-commands "usage: prain [-h] {up,down,restart,status,logs,check,web} ... + +positional arguments: + {up,down,restart,status,logs,check,web} + up [NAME...] start services (all: a b), each waits until ready + down [NAME...] stop services, in reverse order + restart [NAME...] restart services + status [NAME...] show whether services run + logs [NAME...] follow service logs ($HOME/.local/state/prain/NAME.log) + check validate" "$("$p" --help)" exit $fail