Configuring SUPERVISOR for Laravel queues!

5 min readFeb 9, 2019

Hello everyone!

So, After banging my head across multiple articles, posts and many stack overflow thread’s, i finally managed to setup “SUPERVISOR” for laravel queue processing and here i am writing this post that might help someone.

At first, the official documentation appears a neat guide but, for me it was a bit more vague, as i just quickly wanted to setup one for my site. So, further without adding up anything from my story, let me share the steps that worked for me.

For those who don’t know what is “supervisor” here is what it’s official documentation has to say :

Supervisor is a client/server system that allows its users to control a number of processes on UNIX-like operating systems.

(Note : Please make sure before you proceed further you have necessary install permissions)

Installation :

Installation of supervisor is really simple its just like pulling a package from repository! Depending upon installed package manager on your system or your need, you may use any of the following command to install supervisor.

$ pip install supervisor

$ yum install supervisor

$ apt-get install supervisor

$ easy_install supervisor

If installed successfully, after installation supervisor should start running automatically. To check if supervisor is running run following command.

$ ps -aux | grep "supervisor"

Supervisor is running!

Configuration :

Once installed, configuring supervisor is actually pretty straight-forward. All what we need to do is, update it’s configuration file. Supervisor comes bundled with a sample configuration file which we can use directly.

Run the following command to copy the sample configuration file to /etc directory.

$ echo_supervisord_conf > /etc/supervisord.conf

Now, lets create a custom configuration file to manage our queue processing. (though we can directly modify the existing configuration file but, i like to keep the things clean 😅 )

Laravel’s official documentation on queue workers have a nice & clean sample of basic configuration file and we can simply grab that. Here is how it looks, after a bit modifications.

[program:name_of_worker]
process_name=%(program_name)s_%(process_num)02d
command=php /path/to/artisan/binary artisan queue:work --sleep=3 --tries=3
autostart=true
autorestart=true
user=someuser
numprocs=8
redirect_stderr=true
stdout_logfile=/path/to/log/file

I guess, each line in the above snippet is pretty self explanatory! but still the command attribute is the one we are most interested in! (it can be any other process/ command that we might want to monitor)

So, create a file (in my case my-site-supervisorconf.config) under your user directory or where-ever possible and paste the above snippet in it. (Just keep note of the path where you save it !😛 )

In my case, i saved it under my “site” directory.

/home/my-site/public_html/my-site-supervisorconf.config

Now comes the important part, telling supervisor to honor our newly created configuration file. Simply, open the sample configuration file we copied in earlier section under /etc directory with an editor like:

$ vim /etc/supervisord.conf

And head to the bottom of file to locate few lines that are similar to the below ones.

;[include]
;files=/somepath/*.ini

Next, uncomment the [include] directive and append one more line or edit existing line that say's files and specify the path to the newly created configuration file. (I told you to keep note of it 😝). you will end up with something similar to below lines:

[include]
files=/home/my-site/public_html/my-site-supervisorconf.config

(Yeah..i know that, the sample file contains a lot of things, but just ignore them for now… Still, if you are really curious to know what each line does please, refer to the below link http://supervisord.org/configuration.html)

We are almost ready!

Monitoring our processes with supervisor :

So, far we have successfully installed & created a new configuration file that specify the process (queue worker) to be monitored but as supervisor was already started and was running it is unaware of any changes.

lets make supervisor aware of our changes now!

“Supervisor” comes with configuration tool named “supervisorctl” which basically allow us to configure,monitor, start and stop processes running under it.

Lets use, supervisorctl command to add the new configuration changes to currently loaded configuration. To do so, run following command in below sequence.

(Note : though across multiple threads i found, some people recommending running either of commands. but, i followed following sequence and it worked well for me.)

$ supervisorctl reread

$ supervisorctl update

$ supervisorctl start all

$ supervisorctl start job_worker (name of worker you want to run!)

if you followed everything correctly and everything goes well, you should see output similar to following.

and we are DONE!

It was not that difficult right? 😃

NOTE:

If something does not work for you try stopping and then restarting supervisor again with

KILL -s SIGTEM $(supervisorctl pid)

to check number of processes running try running

$ supervisorctl and it will show something like

Updates:

Hey Guys, here are few more things that might help you for debugging common issues.

(March 2020):

Supervisor installed but supervisor.conf file missing?
In few cases when supervisor installed, supervisord.conf file was not published so, here what you can do :
Find the location of supervisord binary with following command and navigate to the directory (here /usr/bin)
$ whereis supervisor

Now, locate the file named echo_supervisord_conf and redirect its output to the location where you want supervisord.conf to be saved by executing the file. Make sure the destination directory exists.

[root@myserver bin]# echo_supervisord_conf > /etc/supervisord/supervisord.conf

execute and redirect output of file output to supervisor.conf file.

2. Another program is using HTTP port :
Error: Another program is already listening on a port that one of our HTTP servers is configured to use. Shut this program down first before starting supervisord.

This issue can be resolved by simply removing the socket file associated and resourcing the supervisor config file.

[Note : The default socket file is /tmp/supervisor.sock file. ]

[root@myserver supervisor]# rm /tmp/supervisor.sock

and

[root@myserver supervisor]# supervisord -c supervisord.conf