From a551dd7553591ccd65487892b3290be0848d86ed Mon Sep 17 00:00:00 2001
From: CREDO23 <bakerathierry@gmail.com>
Date: Fri, 10 Jul 2026 17:17:36 +0200
Subject: [PATCH] feat(docker): start Xvfb when CRAWL_HEADED_XVFB_ENABLED is
 set

For every browser-running role (api/worker/all, not migrate) the entrypoint brings up a virtual display and exports DISPLAY, registering Xvfb for graceful shutdown. Off keeps browsers headless.
---
 .../scripts/docker/entrypoint.sh              | 21 +++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/surfsense_backend/scripts/docker/entrypoint.sh b/surfsense_backend/scripts/docker/entrypoint.sh
index 2efd78f94..4e46d184a 100644
--- a/surfsense_backend/scripts/docker/entrypoint.sh
+++ b/surfsense_backend/scripts/docker/entrypoint.sh
@@ -121,7 +121,28 @@ start_beat() {
     echo "  Celery Beat PID=${PIDS[-1]}"
 }
 
+# ── Headful browser display ──────────────────────────────────
+# Give the stealth browser a virtual display so it can run headful (TikTok's
+# profile feed is empty to headless Chromium). Off => every browser stays headless.
+start_xvfb() {
+    if [ "$(echo "${CRAWL_HEADED_XVFB_ENABLED:-false}" | tr '[:upper:]' '[:lower:]')" != "true" ]; then
+        return
+    fi
+    local display="${XVFB_DISPLAY:-:99}"
+    echo "Starting Xvfb on ${display} (CRAWL_HEADED_XVFB_ENABLED=true)..."
+    Xvfb "${display}" -screen 0 1920x1080x24 -nolisten tcp >/dev/null 2>&1 &
+    PIDS+=($!)
+    export DISPLAY="${display}"
+    sleep 1  # let the X server accept connections before a browser starts
+    echo "  Xvfb PID=${PIDS[-1]} DISPLAY=${DISPLAY}"
+}
+
 # ── Main: run based on role ──────────────────────────────────
+# migrate never launches a browser; every other role might, so start the display.
+if [ "${SERVICE_ROLE}" != "migrate" ]; then
+    start_xvfb
+fi
+
 case "${SERVICE_ROLE}" in
     migrate)
         run_migrations