From a2206d3ac1d1422006ec89bc7de0c17dab8b1873 Mon Sep 17 00:00:00 2001
From: Connor Howington <chowingt@fnal.gov>
Date: Wed, 19 Aug 2026 15:12:16 -0500
Subject: [PATCH] Add documentation for Xpra lifecycle settings

---
 README.md         | 16 ++++++++++++++++
 docker/start.sh   | 49 ++++++++++++++++++++++++++++++++++-------------
 docs/container.md | 16 ++++++++++++++++
 3 files changed, 68 insertions(+), 13 deletions(-)

diff --git a/README.md b/README.md
index 3c696fb..256c190 100644
--- a/README.md
+++ b/README.md
@@ -66,6 +66,22 @@ Read more in [`docs/container.md`](docs/container.md).
 
 The Dockerfile also contains additional internal build stages used to assemble those runtime images.
 
+### Xpra Lifecycle Settings
+
+The Xpra GUI container's shutdown behavior is configured by the lifecycle variables near the top of [`docker/start.sh`](docker/start.sh):
+
+```bash
+XPRA_EXIT_WITH_CHILDREN="${XPRA_EXIT_WITH_CHILDREN:-yes}"
+XPRA_EXIT_WITH_WINDOWS="${XPRA_EXIT_WITH_WINDOWS:-yes}"
+XPRA_SERVER_IDLE_TIMEOUT="${XPRA_SERVER_IDLE_TIMEOUT:-300}"
+```
+
+- `XPRA_EXIT_WITH_CHILDREN` stops Xpra when the launched application process exits. Default: yes
+- `XPRA_EXIT_WITH_WINDOWS` stops Xpra when the application no longer has any windows open. Default: yes
+- `XPRA_SERVER_IDLE_TIMEOUT` controls how many seconds Xpra can remain idle before stopping. Default: 300
+
+Adjust these values in [`docker/start.sh`](docker/start.sh), or override the variables in the deployment environment, when an application needs different lifecycle behavior.
+
 ## FNAL Kerberos Defaults
 
 This template assumes new applications will run in the `FNAL.GOV` Kerberos environment.
diff --git a/docker/start.sh b/docker/start.sh
index 69fdde6..4e025cb 100644
--- a/docker/start.sh
+++ b/docker/start.sh
@@ -1,18 +1,48 @@
 #!/usr/bin/env bash
 set -Eeuo pipefail
 
+################################ Configuration ################################
+######## Edit these defaults or override them through the environment. ########
+
+### Xpra connection settings.
+# Xpra session name.
 APP_NAME="${APP_NAME:-ap-python-starter-kit}"
+# Xpra display number.
 XPRA_DISPLAY="${XPRA_DISPLAY:-:100}"
+# Xpra authentication method (if any).
+XPRA_AUTH="${XPRA_AUTH:-none}"
+
+### Xpra HTML client settings.
+# Enable or disable Xpra's HTML client.
+XPRA_HTML="${XPRA_HTML:-on}"
+# Host and port where Xpra serves its HTML client.
 XPRA_BIND_HOST="${XPRA_BIND_HOST:-0.0.0.0}"
 XPRA_BIND_PORT="${XPRA_BIND_PORT:-14500}"
-XPRA_HTML="${XPRA_HTML:-on}"
-# HTML mode: no password needed, no native client auth.
-XPRA_AUTH="${XPRA_AUTH:-none}"
 
+### Application and logging settings.
+# Command launched by Xpra.
 APP_CMD="${APP_CMD:-python -m ap_python_starter_kit.main}"
+# Paths for Xpra and application logs.
 XPRA_LOG_FILE="${XPRA_LOG_FILE:-/tmp/xpra.log}"
 APP_LOG_FILE="${APP_LOG_FILE:-/tmp/app.log}"
 
+### Xpra lifecycle settings.
+# Stop Xpra when the launched application process (APP_CMD) exits.
+XPRA_EXIT_WITH_CHILDREN="${XPRA_EXIT_WITH_CHILDREN:-yes}"
+# Stop Xpra when the application no longer has any windows open.
+XPRA_EXIT_WITH_WINDOWS="${XPRA_EXIT_WITH_WINDOWS:-yes}"
+# Stop Xpra after this many seconds of server idle time.
+XPRA_SERVER_IDLE_TIMEOUT="${XPRA_SERVER_IDLE_TIMEOUT:-300}"
+
+### Directory settings.
+# Base directory used for writable runtime paths.
+RUNTIME_BASE="${RUNTIME_BASE:-/tmp}"
+# Runtime directories used by Xpra and the application user.
+XDG_RUNTIME_DIR_DEFAULT="${XDG_RUNTIME_DIR:-${RUNTIME_BASE}/runtime-pyuser}"
+XPRA_RUN_DIR_DEFAULT="${XPRA_RUN_DIR:-${RUNTIME_BASE}/xpra}"
+USER_RUN_DIR_DEFAULT="${USER_RUN_DIR:-${RUNTIME_BASE}/user-1000}"
+###############################################################################
+
 cleanup() {
   echo "[start.sh] shutting down"
   xpra stop "${XPRA_DISPLAY}" >/dev/null 2>&1 || true
@@ -20,13 +50,6 @@ cleanup() {
 
 trap cleanup SIGINT SIGTERM EXIT
 
-# Prefer writable runtime dirs when running as non-root (common in OpenShift/K8s).
-# /run is often read-only for unprivileged containers.
-RUNTIME_BASE="${RUNTIME_BASE:-/tmp}"
-XDG_RUNTIME_DIR_DEFAULT="${XDG_RUNTIME_DIR:-${RUNTIME_BASE}/runtime-pyuser}"
-XPRA_RUN_DIR_DEFAULT="${XPRA_RUN_DIR:-${RUNTIME_BASE}/xpra}"
-USER_RUN_DIR_DEFAULT="${USER_RUN_DIR:-${RUNTIME_BASE}/user-1000}"
-
 mkdir -p "${USER_RUN_DIR_DEFAULT}" "${XDG_RUNTIME_DIR_DEFAULT}" "${XPRA_RUN_DIR_DEFAULT}" /tmp/.X11-unix
 chmod 700 "${USER_RUN_DIR_DEFAULT}" "${XDG_RUNTIME_DIR_DEFAULT}" "${XPRA_RUN_DIR_DEFAULT}" || true
 if ! chmod 1777 /tmp/.X11-unix 2>/dev/null; then
@@ -46,9 +69,9 @@ xpra start "${XPRA_DISPLAY}" \
   --html="${XPRA_HTML}" \
   --auth="${XPRA_AUTH}" \
   --daemon=no \
-  --exit-with-children=yes \
-  --exit-with-windows=yes \
-  --server-idle-timeout=300 \
+  --exit-with-children="${XPRA_EXIT_WITH_CHILDREN}" \
+  --exit-with-windows="${XPRA_EXIT_WITH_WINDOWS}" \
+  --server-idle-timeout="${XPRA_SERVER_IDLE_TIMEOUT}" \
   --start-child="/bin/bash -lc '${APP_CMD} >>\"${APP_LOG_FILE}\" 2>&1'" \
   --pulseaudio=no \
   --notifications=no \
diff --git a/docs/container.md b/docs/container.md
index 1619186..b3cb094 100644
--- a/docs/container.md
+++ b/docs/container.md
@@ -76,6 +76,22 @@ make run-gui APP_CMD="python -m ap_python_starter_kit.gui"
 
 For the Xpra image, `APP_CMD` is the supported way to replace the default GUI command that [`docker/start.sh`](docker/start.sh) launches. This override support is specific to the Xpra path and does not apply to the CLI [`runtime`](Dockerfile:62) stage.
 
+### Configure Xpra lifecycle behavior
+
+The Xpra lifecycle settings are defined near the top of [`docker/start.sh`](docker/start.sh), alongside the other variables developers may want to change:
+
+```bash
+XPRA_EXIT_WITH_CHILDREN="${XPRA_EXIT_WITH_CHILDREN:-yes}"
+XPRA_EXIT_WITH_WINDOWS="${XPRA_EXIT_WITH_WINDOWS:-yes}"
+XPRA_SERVER_IDLE_TIMEOUT="${XPRA_SERVER_IDLE_TIMEOUT:-300}"
+```
+
+- `XPRA_EXIT_WITH_CHILDREN` stops Xpra when the launched application process exits.
+- `XPRA_EXIT_WITH_WINDOWS` stops Xpra when the application has no windows left open.
+- `XPRA_SERVER_IDLE_TIMEOUT` controls how many seconds Xpra can remain idle before stopping.
+
+Edit the defaults in [`docker/start.sh`](docker/start.sh) for a project-wide change, or provide the variables through the deployment environment. The current `make run-gui` target does not forward these variables as make arguments.
+
 Security note:
 
 - Xpra HTML is configured with `--auth=none` (no password). Do not expose this port publicly.