{"id":13419794,"url":"https://github.com/rfk/django-supervisor","last_synced_at":"2025-03-15T05:33:13.602Z","repository":{"id":57422226,"uuid":"1858577","full_name":"rfk/django-supervisor","owner":"rfk","description":"easy integration between django and supervisord","archived":true,"fork":false,"pushed_at":"2018-02-24T23:16:13.000Z","size":102,"stargazers_count":380,"open_issues_count":0,"forks_count":63,"subscribers_count":21,"default_branch":"master","last_synced_at":"2024-10-02T03:24:37.418Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rfk.png","metadata":{"files":{"readme":"README.rst","changelog":"ChangeLog.txt","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2011-06-07T06:31:41.000Z","updated_at":"2024-07-20T10:39:49.000Z","dependencies_parsed_at":"2022-09-12T15:43:00.773Z","dependency_job_id":null,"html_url":"https://github.com/rfk/django-supervisor","commit_stats":null,"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rfk%2Fdjango-supervisor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rfk%2Fdjango-supervisor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rfk%2Fdjango-supervisor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rfk%2Fdjango-supervisor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rfk","download_url":"https://codeload.github.com/rfk/django-supervisor/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":221548092,"owners_count":16840968,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-30T22:01:20.959Z","updated_at":"2024-10-26T15:30:36.661Z","avatar_url":"https://github.com/rfk.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"\nStatus: Unmaintained\n====================\n\n.. image:: http://unmaintained.tech/badge.svg\n     :target: http://unmaintained.tech/\n     :alt: No Maintenance Intended\n\nI am `no longer actively maintaining this project \u003chttps://rfk.id.au/blog/entry/archiving-open-source-projects/\u003e`_.\n\n\ndjsupervisor:  easy integration between django and supervisord\n==============================================================\n\n\nDjango-supervisor combines the process-management awesomeness of supervisord\nwith the convenience of Django's management scripts.\n\n\nRationale\n---------\n\nRunning a Django project these days often entails much more than just starting\nup a webserver.  You might need to have Django running under FCGI or CherryPy,\nwith background tasks being managed by celeryd, periodic tasks scheduled by\ncelerybeat, and any number of other processes all cooperating to keep the\nproject up and running.\n\nWhen you're just developing or debugging, it's a pain having to start and\nstop all these different processes by hand.\n\nWhen you're deploying, it's a pain to make sure that each process is hooked\ninto the system startup scripts with the correct configuration.\n\nDjango-supervisor provides a convenient bridge between your Django project\nand the supervisord process control system.  It makes starting all the\nprocesses required by your project as simple as::\n\n    $ python myproject/manage.py supervisor\n\n\nAdvantages\n----------\n\nDjango-supervisor is admittedly quite a thin layer on top of the wonderful\nfunctionality provided by supervisord.  But by integrating tightly with\nDjango's management scripts you gain several advantages:\n\n    * manage.py remains the single point of control for running your project.\n    * Running all those processes is just as easy in development as it\n      is in production.\n    * You get auto-reloading for *all* processes when running in debug mode.\n    * Process configuration can depend on Django settings and environment\n      variables, and have paths relative to your project and/or apps.\n    * Apps can provide default process configurations, which projects can\n      then tweak or override as needed.\n\n\n\nConfiguration\n-------------\n\nDjango-supervisor is a wrapper around supervisord, so it uses the same\nconfiguration file format.  Basically, you write an ini-style config file\nwhere each section defines a process to be launched.  Some examples can be\nfound below, but you'll want to refer to the supervisord docs for all the\nfiner details:\n\n    http://www.supervisord.org\n\n\nTo get started, just include \"djsupervisor\" in your INSTALLED_APPS and drop\na \"supervisord.conf\" file in your project directory, right next to the main\nmanage.py script.\n\nA simple example config might run both the Django development server and the\nCelery task daemon::\n\n    [program:webserver]\n    command={{ PYTHON }} {{ PROJECT_DIR }}/manage.py runserver --noreload\n \n    [program:celeryworker]\n    command={{ PYTHON }} {{ PROJECT_DIR }}/manage.py celery worker -l info\n\n    [program:celerybeat]\n    command={{ PYTHON }} {{ PROJECT_DIR }}/manage.py celery beat -l info\n\nNow when you run the \"supervisor\" management command, it will detect this\nfile and start the two processes for you.\n\nNotice that the config file is interpreted using Django's templating engine.\nThis lets you do fun things like locate files relative to the project root\ndirectory.\n\nBetter yet, you can make parts of the config conditional based on project\nsettings or on the environment.  For example, you might start the development\nserver when debugging but run under FCGI in production::\n\n    [program:webserver]\n    {% if settings.DEBUG %}\n    command={{ PYTHON }} {{ PROJECT_DIR }}/manage.py runserver\n    {% else %}\n    command={{ PYTHON }} {{ PROJECT_DIR }}/manage.py runfcgi host=127.0.0.1 port=8025\n    {% endif %}\n \n\nUsage\n-----\n\nDjango-supervisor provides a new Django management command named \"supervisor\"\nwhich allows you to control all of the processes belonging to your project.\n\nWhen run without arguments, it will spawn supervisord to launch and monitor\nall the configured processs.  Here's some example output using the config\nfile shown in the previous section::\n\n    $ python myproject/manage.py supervisor\n    2011-06-07 23:46:45,253 INFO RPC interface 'supervisor' initialized\n    2011-06-07 23:46:45,253 INFO supervisord started with pid 4787\n    2011-06-07 23:46:46,258 INFO spawned: 'celeryd' with pid 4799\n    2011-06-07 23:46:46,275 INFO spawned: 'webserver' with pid 4801\n    2011-06-07 23:46:47,456 INFO success: webserver entered RUNNING state, process has stayed up for \u003e than 1 seconds (startsecs)\n    2011-06-07 23:46:56,512 INFO success: celeryd entered RUNNING state, process has stayed up for \u003e than 10 seconds (startsecs)\n\nBy default the \"supervisor\" command will stay in the foreground and print\nstatus updates to the console.  Pass the --daemonize option to have it \nrun in the background.  You can also tweak its behaviour using all of\nsupervisord's standard options in the config file.\n\nOnce the supervisor is up and running, you can interact with it to control the\nrunning processes.  Running \"manage.py supervisor shell\" will launch the\ninteractive supervisorctl command shell.  From here you can view process\nstatus and start/stop/restart individual processes::\n\n    $ python myproject/manage.py supervisor shell\n    celeryd                          RUNNING    pid 4799, uptime 0:03:17\n    webserver                        RUNNING    pid 4801, uptime 0:03:17\n    supervisor\u003e \n    supervisor\u003e help\n\n    default commands (type help \u003ctopic\u003e):\n    =====================================\n    add   clear fg       open quit   remove restart  start  stop update \n    avail exit  maintail pid  reload reread shutdown status tail version\n\n    supervisor\u003e \n    supervisor\u003e stop celeryd\n    celeryd: stopped\n    supervisor\u003e \n    supervisor\u003e status\n    celeryd                          STOPPED    Jun 07 11:51 PM\n    webserver                        RUNNING    pid 4801, uptime 0:04:45\n    supervisor\u003e \n\n\nYou can also issue individual process-manangement commands directly on the \ncommand-line::\n\n    $ python myproject/manage.py supervisor start celeryd\n    celeryd: started\n    $\n    $ python myproject/manage.py supervisor status\n    celeryd                          RUNNING    pid 4937, uptime 0:00:55\n    webserver                        RUNNING    pid 4801, uptime 0:09:05\n    $\n    $ python myproject/manage.py supervisor shutdown\n    Shut down\n    $\n\n\nFor details of all the available management commands, consult the supervisord\ndocumentation.\n\n\nCommand-Line Options\n~~~~~~~~~~~~~~~~~~~~\n\nThe \"supervisor\" command accepts the following options:\n\n  --daemonize             run the supervisord process in the background\n  --pidfile               store PID of supervisord process in this file\n  --logfile               write supervisord logs to this file\n  --project-dir           use this as the django project directory\n  --launch=program        launch program automatically at supervisor startup\n  --nolaunch=program      don't launch program automatically at startup\n  --exclude=program       remove program from the supervisord config\n  --include=program       include program in the supervisord config\n  --autoreload=program    restart program when code files change\n  --noreload              don't restart programs when code files change\n\n\nExtra Goodies\n-------------\n\nDjango-supervisor provides some extra niceties on top of the configuration\nlanguage of supervisord.\n\n\nTemplating\n~~~~~~~~~~\n\nAll supervisord.conf files are rendered through Django's templating system.\nThis allows you to interpolate values from the settings or environment, and\nconditionally switch processes on or off.  The template context for each\nconfiguration file contains the following variables::\n\n    PROJECT_DIR          the top-level directory of your project (i.e. the\n                         directory containing your manage.py script).\n\n    APP_DIR              for app-provided config files, the top-level\n                         directory containing the application code.\n\n    PYTHON               full path to the current python interpreter.\n\n    SUPERVISOR_OPTIONS   the command-line options passed to manage.py. \n \n    settings             the Django settings module, as seen by your code.\n\n    environ              the os.environ dict, as seen by your code.\n\n\n\nDefaults, Overrides and Excludes\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nDjango-supervisor recognises some special config-file options that are useful\nwhen merging multiple app-specific and project-specific configuration files.\n\nThe [program:__defaults__] section can be used to provide default options\nfor all other [program] sections.  These options will only be used if none\nof the config files found by django-supervisor provide that option for\na specific program.\n\nThe [program:__overrides__] section can be used to override options for all\nconfigured programs.  These options will be applied to all processes regardless\nof what any other config file has to say.\n\nFinally, you can completely disable a [program] section by setting the option\n\"exclude\" to true.  This is mostly useful for disabling process definitions\nprovided by a third-party application.\n\nHere's an example config file that shows them all in action::\n\n    ; We want all programs to redirect stderr by default,\n    ; unless specifically configured otherwise.\n    [program:__defaults__]\n    redirect_stderr=true\n\n    ; We force all programs to run as user \"nobody\"\n    [program:__overrides__]\n    user=nobody\n\n    ; Disable auto-reloading on code changes by excluding that program.\n    [program:autoreload]\n    exclude=true\n\n\n\nAutomatic Control Socket Config\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThe supervisord and supervisorctl programs interact with each other via an\nXML-RPC control socket.  This provides a great deal of flexibility and control\nover security, but you have to configure it just so or things won't work.\n\nFor convenience during development, django-supervisor provides automatic\ncontrol socket configuration.  By default it binds the server to localhost\non a fixed-but-randomish port, and sets up a username and password based on\nsettings.SECRET_KEY.\n\nFor production deployment, you might like to reconfigure this by setting up\nthe [inet_http_server] or [unix_http_server] sections.  Django-supervisor\nwill honour any such settings you provide.\n\n\n\nAutoreload\n~~~~~~~~~~\n\nWhen running in debug mode, django-supervisor automatically defines a process\nnamed \"autoreload\".  This is very similar to the auto-reloading feature of\nthe Django development server, but works across all configured processes.\nFor example, this will let you automatically restart both the dev server and\nceleryd whenever your code changes.\n\nTo prevent an individual program from being auto-reloaded, set its \"autoreload\"\noption to false::\n\n    [program:non-python-related]\n    autoreload=false\n\nTo switch off the autoreload process entirely, you can pass the --noreload \noption to supervisor or just exclude it in your project config file like so::\n\n    [program:autoreload]\n    exclude=true\n\nOptionally, the file patterns on which autoreload listens for changes can\nbe set in your project's settings.py:\n\n    SUPERVISOR_AUTORELOAD_PATTERNS = [\"*.py\", \"*.pyc\", \"*.pyo\"]\n    SUPERVISOR_AUTORELOAD_IGNORE_PATTERNS = [\".*\", \"#*\", \"*~\"]\n\n\n\nMore Info\n---------\n\nThere aren't any more docs online yet.  Sorry.  I'm working on a little tutorial\nand some examples, but I need to actually *use* the project a little more\nfirst to make sure it all fits together the way I want...\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frfk%2Fdjango-supervisor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frfk%2Fdjango-supervisor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frfk%2Fdjango-supervisor/lists"}