From 184e4baa842dd9301eaa1a50db8286fc4f40ec7a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Sascha=20I=C3=9Fbr=C3=BCcker?=
 <sascha.issbruecker@googlemail.com>
Date: Mon, 5 Jan 2026 18:41:50 +0100
Subject: [PATCH] Add option to run supervisor as main process (#1270)

* Add option to run supervisor as main process

* use new option in test script
---
 .dockerignore                              |  3 +-
 bootstrap.sh                               | 16 ++++++----
 docs/src/content/docs/options.md           | 12 +++++++
 scripts/run-docker.sh                      |  1 +
 supervisord-all.conf                       | 37 ++++++++++++++++++++++
 supervisord.conf => supervisord-tasks.conf |  0
 6 files changed, 62 insertions(+), 7 deletions(-)
 create mode 100644 supervisord-all.conf
 rename supervisord.conf => supervisord-tasks.conf (100%)

diff --git a/.dockerignore b/.dockerignore
index a072bff..7d58b6e 100644
--- a/.dockerignore
+++ b/.dockerignore
@@ -12,7 +12,8 @@
 !/postcss.config.js
 !/pyproject.toml
 !/rollup.config.mjs
-!/supervisord.conf
+!/supervisord-tasks.conf
+!/supervisord-all.conf
 !/uv.lock
 !/uwsgi.ini
 !/version.txt
diff --git a/bootstrap.sh b/bootstrap.sh
index 24e0063..537758c 100755
--- a/bootstrap.sh
+++ b/bootstrap.sh
@@ -27,10 +27,14 @@ python manage.py migrate_tasks
 # Ensure folders are owned by the right user
 chown -R www-data: /etc/linkding/data
 
-# Start background task processor using supervisord, unless explicitly disabled
-if [ "$LD_DISABLE_BACKGROUND_TASKS" != "True" ]; then
-  supervisord -c supervisord.conf
+# Start processes
+# Experimental: use supervisor to manage all processes, enables logging background tasks to stdout/stderr
+if [ "$LD_SUPERVISOR_MANAGED" = "True" ]; then
+  exec supervisord -c supervisord-all.conf
+# Default: start background task processor as daemon, then uwsgi as main process
+else
+  if [ "$LD_DISABLE_BACKGROUND_TASKS" != "True" ]; then
+    supervisord -c supervisord-tasks.conf
+  fi
+  exec uwsgi --http $LD_SERVER_HOST:$LD_SERVER_PORT uwsgi.ini
 fi
-
-# Start uwsgi server
-exec uwsgi --http $LD_SERVER_HOST:$LD_SERVER_PORT uwsgi.ini
diff --git a/docs/src/content/docs/options.md b/docs/src/content/docs/options.md
index 6cdebde..6378c6d 100644
--- a/docs/src/content/docs/options.md
+++ b/docs/src/content/docs/options.md
@@ -48,6 +48,18 @@ Disables background tasks, such as creating snapshots for bookmarks on the [the
 Enabling this flag will prevent the background task processor from starting up, and prevents scheduling tasks.
 This might be useful if you are experiencing performance issues or other problematic behaviour due to background task processing.
 
+### `LD_SUPERVISOR_MANAGED` (Experimental)
+
+Values: `True`, `False` | Default = `False`
+
+Changes how processes are managed within the container.
+When enabled, supervisor manages both the background task processor and the web server (uwsgi).
+This enables background task logs to appear in the container output (visible via `docker logs`).
+At the moment, supervisor will automatically restart crashed processes and the `LD_DISABLE_BACKGROUND_TASKS` setting is ignored.
+
+When disabled (default), the background task processor runs as a daemon and uwsgi runs as the main process.
+Background task logs are written to a file (`background_tasks.log`) instead of the container output.
+
 ### `LD_DISABLE_URL_VALIDATION`
 
 Values: `True`, `False` | Default = `False`
diff --git a/scripts/run-docker.sh b/scripts/run-docker.sh
index 96d3a96..c85057d 100755
--- a/scripts/run-docker.sh
+++ b/scripts/run-docker.sh
@@ -9,4 +9,5 @@ docker rm -f linkding-local || true
 docker run --name linkding-local --rm -p 9090:9090  \
   -e LD_SUPERUSER_NAME=admin \
   -e LD_SUPERUSER_PASSWORD=admin \
+  -e LD_SUPERVISOR_MANAGED=True \
   sissbruecker/linkding:local
diff --git a/supervisord-all.conf b/supervisord-all.conf
new file mode 100644
index 0000000..a06bc00
--- /dev/null
+++ b/supervisord-all.conf
@@ -0,0 +1,37 @@
+# Supervisor config that manages both uwsgi and background jobs
+# Used when LD_SUPERVISOR_MANAGED is enabled, which also enables logging background tasks output to container logs
+[supervisord]
+user=root
+nodaemon=true
+loglevel=info
+
+[program:uwsgi]
+command=/bin/bash -c 'uwsgi --http ${LD_SERVER_HOST:-[::]}:${LD_SERVER_PORT:-9090} uwsgi.ini'
+stdout_logfile=/dev/fd/1
+stdout_logfile_maxbytes=0
+stderr_logfile=/dev/fd/2
+stderr_logfile_maxbytes=0
+stopasgroup=true
+autorestart=true
+
+[program:jobs]
+user=www-data
+# setup a temp home folder for the job, required by chromium
+environment=HOME=/tmp/home
+command=python manage.py run_huey -f
+stdout_logfile=/dev/fd/1
+stdout_logfile_maxbytes=0
+stderr_logfile=/dev/fd/2
+stderr_logfile_maxbytes=0
+stopasgroup=true
+autorestart=true
+
+[unix_http_server]
+file=/var/run/supervisor.sock
+chmod=0700
+
+[rpcinterface:supervisor]
+supervisor.rpcinterface_factory = supervisor.rpcinterface:make_main_rpcinterface
+
+[supervisorctl]
+serverurl=unix:///var/run/supervisor.sock
diff --git a/supervisord.conf b/supervisord-tasks.conf
similarity index 100%
rename from supervisord.conf
rename to supervisord-tasks.conf