Home

Awesome

Go Report Card

Why this project?

The python script supervisord is a powerful tool used by a lot of guys to manage the processes. I like supervisord too.

But this tool requires that the big python environment be installed in target system. In some situation, for example in the docker environment, the python is too big for us.

This project re-implements supervisord in go-lang. Compiled supervisord is very suitable for environments where python is not installed.

Building the supervisord

Before compiling the supervisord, make sure the go-lang 1.11+ is installed in your environment.

To compile supervisord for linux, run following commands:

  1. go generate
  2. GOOS=linux go build -tags release -a -ldflags "-linkmode external -extldflags -static" -o supervisord

Run the supervisord

After a supervisord binary has been generated, create a supervisord configuration file and start the supervisord like this:

$ cat supervisor.conf
[program:test]
command = /your/program args
$ supervisord -c supervisor.conf

Please note that config-file location autodetected in this order:

  1. $CWD/supervisord.conf
  2. $CWD/etc/supervisord.conf
  3. /etc/supervisord.conf
  4. /etc/supervisor/supervisord.conf (since Supervisor 3.3.0)
  5. ../etc/supervisord.conf (Relative to the executable)
  6. ../supervisord.conf (Relative to the executable)

Run as daemon with web-ui

Add the inet interface in your configuration:

[inet_http_server]
port=127.0.0.1:9001

then run

$ supervisord -c supervisor.conf -d

In order to manage the daemon, you can use supervisord ctl subcommand, available subcommands are: status, start, stop, shutdown, reload.

$ supervisord ctl status
$ supervisord ctl status program-1 program-2...
$ supervisord ctl status group:*
$ supervisord ctl stop program-1 program-2...
$ supervisord ctl stop group:*
$ supervisord ctl stop all
$ supervisord ctl start program-1 program-2...
$ supervisord ctl start group:*
$ supervisord ctl start all
$ supervisord ctl shutdown
$ supervisord ctl reload
$ supervisord ctl signal <signal_name> <process_name> <process_name> ...
$ supervisord ctl signal all
$ supervisord ctl pid <process_name>
$ supervisord ctl fg <process_name>

Please note that supervisor ctl subcommand works correctly only if http server is enabled in [inet_http_server], and serverurl correctly set. Unix domain socket is not currently supported for this pupose.

Serverurl parameter detected in the following order:

Check the version

Command "version" will show the current supervisord binary version.

$ supervisord version

Supported features

Http server

Http server can work via both unix domain socket and TCP. Basic auth is optional and supported too.

The unix domain socket setting is in the "unix_http_server" section. The TCP http server setting is in "inet_http_server" section.

If both "inet_http_server" and "unix_http_server" are not set up in the configuration file, no http server will be started.

Supervisord daemon settings

Following parameters configured in "supervisord" section:

Supervised program settings

Supervised program settings configured in [program:programName] section and include these options:

[program:A]
depends_on = B, C

[program:B]
...
[program:C]
...

Set default parameters for all supervised programs

All common parameters that are identical for all supervised programs can be defined once in "program-default" section and omitted in all other program sections.

In example below the VAR1 and VAR2 environment variables apply to both test1 and test2 supervised programs:

[program-default]
environment=VAR1="value1",VAR2="value2"
envFiles=global.env,prod.env

[program:test1]
...

[program:test2]
...

Group

Section "group" is supported and you can set "programs" item

Events

Supervisord 3.x defined events are supported partially. Now it supports following events:

Logs

Supervisord can redirect stdout and stderr ( fields stdout_logfile, stderr_logfile ) of supervised programs to:

Multiple log files can be configured for the stdout_logfile and stderr_logfile with ',' as delimiter. For example:

stdout_logfile = test.log, /dev/stdout

syslog settings

if write the log to the syslog, following additional parameter can be set like:

syslog_facility=local0
syslog_tag=test
syslog_stdout_priority=info
syslog_stderr_priority=err

Web GUI

Supervisord has builtin web GUI: you can start, stop & check the status of program from the GUI. Following picture shows the default web GUI:

alt text

Please note that in order to see|use Web GUI you should configure it in /etc/supervisord.conf both in [inet_http_server] (and|or [unix_http_server] if you prefer unix domain socket) and [supervisorctl]:

[inet_http_server]
port=127.0.0.1:9001
;username=test1
;password=thepassword

[supervisorctl]
serverurl=http://127.0.0.1:9001

Usage from a Docker container

supervisord is compiled inside a Docker image to be used directly inside another image, from the Docker Hub version.

FROM debian:latest
COPY --from=ochinchina/supervisord:latest /usr/local/bin/supervisord /usr/local/bin/supervisord
CMD ["/usr/local/bin/supervisord"]

Integrate with Prometheus

The Prometheus node exporter supported supervisord metrics are now integrated into the supervisor. So there is no need to deploy an extra node_exporter to collect the supervisord metrics. To collect the metrics, the port parameter in section "inet_http_server" must be configured and the metrics server is started on the path /metrics of the supervisor http server.

For example, if the port parameter in "inet_http_server" is "127.0.0.1:9001" and then the metrics server should be accessed in url "http://127.0.0.1:9001/metrics"

Register service

Autostart supervisord after os started. Look up supported platforms at kardianos/service.

# install
sudo supervisord service install -c full_path_to_conf_file
# uninstall
sudo supervisord service uninstall
# start
supervisord service start
# stop
supervisord service stop