koopa-admin-log/scripts/castopod/README.md

Castopod ops scripts (koopa)

Live stack: /home/hernani/koopa-castopod/ (podman-compose).
These scripts live in admin-log and should be copied to the host when changed.

Hang-avoidance rules (learned 2026-07-09)

Failure mode	What hung	Fix in scripts
php spark shield:user activate	interactive [y,n] without TTY → TypeError / hang	SQL: UPDATE cp_users SET active=1 via cp_activate_users
bare curl / image pulls	no deadline → agent waits forever	curl --connect-timeout + --max-time; timeout(1) around podman-compose pull
health loops	infinite sleep	capped CP_HEALTH_TRIES + fail
Wikimedia/random downloads	slow/blocked CDN	local/known files only; always --max-time
empty optional file fields	Castopod validates empty transcript/chapters	send real .srt / .json or omit fields carefully

Usage (on koopa as hernani)

# copy once
mkdir -p ~/koopa-castopod/bin
cp /path/to/koopa-admin-log/scripts/castopod/{lib.sh,status.sh,up.sh} ~/koopa-castopod/bin/
chmod +x ~/koopa-castopod/bin/*.sh

~/koopa-castopod/bin/status.sh
~/koopa-castopod/bin/up.sh

Env overrides: CP_MAX_TIME, CP_PULL_TIMEOUT, CP_HEALTH_TRIES, CP_BASEURL.

Passwords stay in ~/koopa-castopod/.env and users.env (mode 600) — never in admin-log.