Merge pull request #45 from knifecake/fix/pidfile-default-none

Align supervisor pidfile behavior with Solid Queue

Author: knifecake

CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## Unreleased
+
+## v0.1.8 - 2026-03-08
+
+**Fixed:**
+
+- Default `steady_queue.supervisor_pidfile` is now `None` (disabled by
+  default), matching Solid Queue and avoiding stale pidfile issues in
+  containerized deployments.
+- Supervisor pidfiles now register an `atexit` cleanup hook so graceful exits
+  remove the pidfile more reliably.
+
 ## v0.1.7 - 2026-02-21
 
 **Added:**

README.md

@@ -479,8 +479,7 @@ There are several settings that control how Steady Queue works that you can set
   requesting immediate termination—defaults to 5 seconds.
 - `supervisor_pidfile`: path to a pidfile that the supervisor will create when
   booting to prevent running more than one supervisor in the same host, or in
-  case you want to use it for a health check. It's set to
-  `tmp/pids/steady_queue_supervisor.pid` by default.
+  case you want to use it for a health check. It's `None` by default.
 - `preserve_finished_jobs`: whether to keep finished jobs in the
   `steady_queue_jobs` table—defaults to `True`.
 - `clear_finished_jobs_after`: period to keep finished jobs around, in case

docs/configuration.rst

@@ -189,7 +189,7 @@ Available settings:
 ``steady_queue.supervisor_pidfile``
     Path to a PID file created by the supervisor. Used to prevent multiple
     supervisors on the same host and as a health check target. Defaults to
-    ``tmp/pids/steady_queue_supervisor.pid``.
+    ``None``.
 
 ``steady_queue.preserve_finished_jobs``
     Whether to keep finished jobs in the ``steady_queue_jobs`` table. Defaults

steady_queue/__init__.py

@@ -17,6 +17,6 @@
 
 default_concurrency_control_period: timedelta = timedelta(minutes=3)
 
-supervisor_pidfile: Optional[str] = "tmp/pids/steady_queue_supervisor.pid"
+supervisor_pidfile: Optional[str] = None
 
 database: str = "default"

steady_queue/processes/pidfile.py

@@ -1,3 +1,4 @@
+import atexit
 import os
 
 
@@ -9,6 +10,7 @@ def __init__(self, path: str):
     def setup(self):
         self.check_status()
         self.write_file()
+        self.set_at_exit_hook()
 
     def delete(self):
         self.delete_file()
@@ -36,6 +38,9 @@ def write_file(self):
             self.check_status()
             self.write_file()
 
+    def set_at_exit_hook(self):
+        atexit.register(lambda: self.delete() if os.getpid() == self.pid else None)
+
     def delete_file(self):
         try:
             os.unlink(self.path)

tests/test_pidfile.py

@@ -0,0 +1,42 @@
+import os
+from tempfile import TemporaryDirectory
+from unittest.mock import patch
+
+from django.test import SimpleTestCase
+
+import steady_queue
+from steady_queue.processes.pidfile import Pidfile
+
+
+class PidfileDefaultsTestCase(SimpleTestCase):
+    def test_supervisor_pidfile_defaults_to_none(self):
+        self.assertIsNone(steady_queue.supervisor_pidfile)
+
+
+class PidfileLifecycleTestCase(SimpleTestCase):
+    def test_setup_registers_atexit_cleanup_hook(self):
+        with TemporaryDirectory() as temp_dir, patch("atexit.register") as register:
+            path = os.path.join(temp_dir, "pids", "steady_queue_supervisor.pid")
+
+            pidfile = Pidfile(path)
+            pidfile.setup()
+
+            register.assert_called_once()
+            self.assertTrue(os.path.exists(path))
+            with open(path) as f:
+                self.assertEqual(str(os.getpid()), f.read().strip())
+
+    def test_setup_replaces_stale_pidfile_for_dead_process(self):
+        with TemporaryDirectory() as temp_dir:
+            path = os.path.join(temp_dir, "pids", "steady_queue_supervisor.pid")
+
+            os.makedirs(os.path.dirname(path), exist_ok=True)
+            with open(path, "w") as f:
+                f.write("999999")
+
+            with patch("atexit.register"):
+                pidfile = Pidfile(path)
+                pidfile.setup()
+
+            with open(path) as f:
+                self.assertEqual(str(os.getpid()), f.read().strip())