fix(docker): bound the shutdown wait so a stuck process cannot strand PID 1

stop_process_pid signalled each managed process and then waited on it
forever. A process that refuses to exit therefore wedges PID 1, and the
container sits "Up" serving nothing. No restart policy can detect that,
because policies only react to exits.

Valkey reaches exactly that state: it aborts its own shutdown when the
snapshot it writes on exit cannot be written, so on a read-only
/redis-data it catches SIGTERM and keeps running. Because the init script
traps EXIT, every fatal error path runs shutdown(), including a failed
startup migration when the database is not reachable yet. The daemon's
restart policy does not honour compose's depends_on at host boot, so RomM
regularly starts before its database and takes that path. The result is
permanent downtime that needs a manual restart.

Wait STOP_TIMEOUT (default 10s) for a signalled process, then escalate to
SIGKILL, with a second bounded wait and a warning if even that fails. The
failing path now ends in an exit, which a restart policy can act on. Add a
healthcheck to the compose example as well, since a hung PID 1 is
otherwise invisible.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: XenuIsWatching

docker/init_scripts/init

@@ -23,6 +23,9 @@ REDIS_HOST="${REDIS_HOST:=""}"
 # hour of sessions and cached metadata. Set to an empty value to never snapshot.
 REDIS_SAVE_POLICY="${REDIS_SAVE_POLICY="3600 1"}"
 
+# how long to wait for a signalled process to exit before escalating to SIGKILL
+STOP_TIMEOUT="${STOP_TIMEOUT:="10"}"
+
 # logger colors
 RED='\033[0;31m'
 LIGHTMAGENTA='\033[0;95m'
@@ -305,15 +308,39 @@ watchdog_process_pid() {
 	fi
 }
 
+# Wait for PID $1 to disappear, polling every 100ms for at most $2 polls.
+# Returns non-zero if it is still alive when the budget runs out.
+wait_for_pid_exit() {
+	local pid=$1 max_polls=$2 polls=0
+	while [[ -e "/proc/${pid}" ]]; do
+		if ((polls >= max_polls)); then
+			return 1
+		fi
+		sleep 0.1
+		polls=$((polls + 1))
+	done
+	return 0
+}
+
 stop_process_pid() {
 	PROCESS=$1
 	if [[ -f "/tmp/${PROCESS}.pid" ]]; then
 		PID=$(cat "/tmp/${PROCESS}.pid") || true
 		if [[ -d "/proc/${PID}" ]]; then
 			info_log "Stopping ${PROCESS}"
 			kill "${PID}" || true
-			# wait for process exit
-			while [[ -e "/proc/${PID}" ]]; do sleep 0.1; done
+
+			# A process that will not exit must never strand PID 1. Valkey aborts
+			# its own shutdown when the snapshot it writes on exit fails, so on a
+			# read-only /redis-data an unbounded wait here leaves the container up
+			# and serving nothing, which no restart policy can detect.
+			if ! wait_for_pid_exit "${PID}" $((STOP_TIMEOUT * 10)); then
+				warn_log "${PROCESS} did not exit within ${STOP_TIMEOUT}s, sending SIGKILL"
+				kill -9 "${PID}" || true
+				if ! wait_for_pid_exit "${PID}" $((STOP_TIMEOUT * 10)); then
+					warn_log "${PROCESS} survived SIGKILL, continuing shutdown without it"
+				fi
+			fi
 		fi
 	fi
 }

docs/BACKEND_ARCHITECTURE.md

@@ -1516,13 +1516,14 @@ Falls back to `FakeRedis` in test mode.
 
 #### Core
 
-| Variable         | Default          | Description          |
-| ---------------- | ---------------- | -------------------- |
-| `ROMM_BASE_PATH` | `/romm`          | Base data directory  |
-| `ROMM_BASE_URL`  | `http://0.0.0.0` | Application base URL |
-| `ROMM_PORT`      | `8080`           | Server port          |
-| `DEV_MODE`       | `false`          | Development mode     |
-| `LOGLEVEL`       | `INFO`           | Log level            |
+| Variable         | Default          | Description                        |
+| ---------------- | ---------------- | ---------------------------------- |
+| `ROMM_BASE_PATH` | `/romm`          | Base data directory                |
+| `ROMM_BASE_URL`  | `http://0.0.0.0` | Application base URL               |
+| `ROMM_PORT`      | `8080`           | Server port                        |
+| `DEV_MODE`       | `false`          | Development mode                   |
+| `LOGLEVEL`       | `INFO`           | Log level                          |
+| `STOP_TIMEOUT`   | `10`             | Seconds before SIGKILL on shutdown |
 
 #### Database
 

env.template

@@ -4,6 +4,7 @@ ROMM_TMP_PATH=  # Custom temporary directory path
 ROMM_BASE_URL=http://0.0.0.0  # Public URL of this instance
 ROMM_PORT=8080  # Port on which the application listens
 KIOSK_MODE=false  # Read-only mode for public displays or kiosks
+STOP_TIMEOUT=10  # Seconds to wait for a service to exit on shutdown before sending SIGKILL
 
 # Database
 ROMM_DB_DRIVER=mariadb  # Database driver to use (mariadb, mysql, postgresql)

examples/docker-compose.example.yml

@@ -27,6 +27,18 @@ services:
       - /path/to/config:/romm/config # (Optional) Path where config.yml is stored
     ports:
       - 80:8080
+    healthcheck:
+      # $$ defers expansion to the container, so a custom ROMM_PORT still works
+      test:
+        [
+          "CMD-SHELL",
+          "curl -fsS http://localhost:$${ROMM_PORT:-8080}/api/heartbeat",
+        ]
+      start_period: 60s
+      start_interval: 10s
+      interval: 30s
+      timeout: 5s
+      retries: 3
     depends_on:
       romm-db:
         condition: service_healthy