{"id":14950,"library":"supervisord-dependent-startup","title":"Supervisord Dependent Startup","description":"supervisord-dependent-startup is a plugin for Supervisor (a process control system) that allows services to start only after their specified dependent services have reached a 'RUNNING' state. It addresses a common challenge where services require others to be fully operational before they can reliably launch. The current version is 1.4.0, and releases are generally made to support new Supervisor versions or address specific use cases, leading to an infrequent but stable release cadence.","status":"active","version":"1.4.0","language":"en","source_language":"en","source_url":"https://github.com/bendikro/supervisord-dependent-startup","tags":["supervisor","plugin","startup","process management","dependencies"],"install":[{"cmd":"pip install supervisord-dependent-startup","lang":"bash","label":"Install library"}],"dependencies":[{"reason":"This is a plugin for Supervisor and requires Supervisor version 4.0.0 or higher to function.","package":"supervisor","optional":false}],"imports":[{"note":"While this module can be imported, this library is primarily used as a Supervisord event listener and is executed by Supervisord via `python -m supervisord_dependent_startup.listener`, not typically imported directly into user Python code for application logic.","symbol":"listener","correct":"from supervisord_dependent_startup import listener"}],"quickstart":{"code":"import os\n\n# This Python quickstart demonstrates how the core listener module\n# of 'supervisord-dependent-startup' can be referenced. \n# IMPORTANT: This library is a Supervisord plugin and is NOT typically \n# used by importing it directly into your application's Python code.\n# It is executed by Supervisord itself.\n\ntry:\n    from supervisord_dependent_startup import listener\n    print(f\"Successfully imported the Supervisord listener module: {listener.__name__}\")\n    print(f\"Path: {listener.__file__}\")\n    print(\"\\nThis module is designed to be run as an eventlistener via supervisord.conf:\")\n    print(\"\\n  [eventlistener:dependent-startup]\")\n    print(\"  command=python -m supervisord_dependent_startup.listener\")\n    print(\"  events=PROCESS_STATE\")\n    print(\"\\nTo truly 'start' this plugin, you must configure Supervisord and launch Supervisord itself.\")\nexcept ImportError as e:\n    print(f\"Error importing supervisord_dependent_startup.listener: {e}\")\n    print(\"Please ensure 'pip install supervisord-dependent-startup' is complete.\")\n\n# A more practical quickstart would involve a supervisord.conf file, e.g.:\n#\n# [program:db_service]\n# command=python /path/to/db_mock.py\n# priority=100\n#\n# [program:my_app]\n# command=python /path/to/my_app.py\n# priority=200\n# dependencies=db_service # <-- This is where the magic happens!\n#\n# For full setup, refer to the project's GitHub README.","lang":"python","description":"This quickstart illustrates the programmatic reference to the `supervisord_dependent_startup.listener` module. However, the primary use case for this library is via configuration in `supervisord.conf`, where Supervisord executes the listener as an event handler. The Python code below shows the import path and explains how the plugin is actually used within Supervisord's ecosystem, rather than directly by a user's Python application."},"warnings":[{"fix":"Ensure your Supervisor installation is version 4.0.0 or newer. Upgrade Supervisor if necessary.","message":"This plugin requires Supervisor version 4.0.0 or higher. Using it with older Supervisor versions may lead to unexpected behavior or failure to load the event listener.","severity":"gotcha","affected_versions":"<1.4.0 (for older Supervisord versions), all (for Supervisor < 4.0.0)"},{"fix":"Thoroughly test your dependent services to ensure they reliably transition to the `RUNNING` state. Check your program logs for errors preventing full startup.","message":"The `dependencies` option relies on dependent processes reaching the `RUNNING` state. Processes stuck in `STARTING`, `BACKOFF`, or `STOPPED` states will prevent dependent programs from starting.","severity":"gotcha","affected_versions":"all"},{"fix":"Carefully consider if you need a specific stop signal for dependent services. If so, configure `dependencies_stop_signal` with the desired signal (e.g., `TERM`, `QUIT`). Otherwise, rely on Supervisor's `stopwaitsecs` and `stopsignal`.","message":"When configuring `dependencies_stop_signal` on a program, it overrides Supervisord's `stopwaitsecs` for that specific program during the stop sequence. If not set, `stopwaitsecs` applies.","severity":"gotcha","affected_versions":"all"},{"fix":"Update your `supervisord.conf` files to use `dependencies=service1,service2` instead of `ordered_startup_dependencies=service1,service2`.","message":"If migrating from the predecessor `ordered-startup-supervisord`, note that the configuration option for dependencies has changed from `ordered_startup_dependencies` to simply `dependencies`.","severity":"breaking","affected_versions":"Users migrating from `ordered-startup-supervisord` to `supervisord-dependent-startup`"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Verify that `pip install supervisord-dependent-startup` was run in the correct environment. Ensure `python -m supervisord_dependent_startup.listener` executes correctly from the command line in the Supervisord's context. Use an absolute path to the Python executable if necessary (e.g., `/usr/bin/python3 -m supervisord_dependent_startup.listener`).","cause":"The `command` path for the eventlistener in `supervisord.conf` is incorrect, or the Python environment where supervisord is running does not have `supervisord-dependent-startup` installed or accessible.","error":"ERROR (no such file) trying to run command python -m supervisord_dependent_startup.listener"},{"fix":"Review your `dependencies` settings for all programs and redesign your startup order to eliminate circular references. One program must eventually be able to start without waiting for another in the cycle.","cause":"Your `supervisord.conf` configuration defines a circular dependency chain between two or more programs (e.g., A depends on B, and B depends on A).","error":"Error: The program 'my_app' has a circular dependency."},{"fix":"Inspect the logs and status of the dependent services (`db_service` in this example) using `supervisorctl status` and `supervisorctl tail db_service` to identify why they are not reaching the `RUNNING` state.","cause":"One or more of the programs listed in the `dependencies` option for 'my_app' failed to transition to the `RUNNING` state, preventing 'my_app' from being started by the plugin.","error":"Process 'my_app' did not start; dependencies 'db_service' did not reach RUNNING state."}],"ecosystem":"pypi"}