When setting up this blog I came across the problem of needing NodeJS to be running all of the time and start on startup without me having to SSH to the server and start it my self. As well as run in the background.


Doing a quick google search and you may see the NodeJS Forever cli tool popping up. While this does the job well, it only works for nodejs projects and is currently not usable for any other scripts you wish to run on your server.

This is fine if you are only ever going to want to ensure that your NodeJS server is running, but what if you want to watch other processes? Perhaps you have a Laravel install running on the same server and you also want to watch its artisan queue:listen command. Well, with Forever, that isint possible and this may lead you to installing supervisor anyway. So why not use supervisor for both?


Taken from the Supervisor website.

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

Previously I had only used Supervisor for monitoring Laravel's artisan commands and a few simple .sh scripts that were needed for a project. Luckily, Supervisor is very simple to use. Setting up NodeJS to run automatically and permanantly was very easy.

NodeJS + Supervisor

Lets assume the following.

  • You are running on an Ubuntu 12.04 - 14.04 system.
  • NodeJS + NPM have been installed.
  • A project is setup and ready to go located at /var/www/node/myproject.

Installing Supervisor

Lets start with ensuring our system is up-to-date and ready to go.

sudo apt-get update
sudo apt-get upgrade

Install supervisor with the following command.

sudo apt-get install supervisor

Once this has completed, supervisor will be installed and should already be running. Supervisor also comes bundles with an init script that will ensure that it starts when your server boots up. If at any time you need to restart the full service, you can use the below command.

sudo service supervisor restart

Supervisor Programs

Supervisor uses scripts that it calls programs to define what it should be monitoring. Creating a new program is as simple as adding a .conf file to the /etc/supervisor/conf.d directory.

Lets save add a new file called run-mysite.co.uk.conf to the /etc/supervisor/conf.d directory.

sudo nano /etc/supervisor/conf.d/run-mysite.co.uk.conf

Here is a list of the settings that we will be adding to the .conf file.

  • Add a program name using [program:run-mysite.co.uk].
  • Set a working directory using directory=/var/www/node/myproject
  • Add the command to run using command=npm start --production
  • Enable autostarting using autostart=true
  • Enable autorestart using autorestart=true
  • Add an error log file using stderr_logfile=/var/log/run-mysite.co.uk.err.log

With all of these options setup, you should have a file similar to the one below.

command=npm start --production

Looking for more config options? Checkout the Supervisor Documentation

Registering Programs

With the program now created, it needs to be registered with Supervisor to take hold. This is done by rereading and updating Supervisor through its command interface.

Enter the Supervisor command interface by typing the following command.

sudo supervisorctl

If you wish to view all commands, you can do so by typing help. If you wish to exit, you can use the normal cmd+c keyboard shortcut. The commands we will take a look at are reread, update, start and tail.

To have our new program take place, we need to run the reread command and the update command.

user@myserver:~$ sudo supervisorctl
supervisor> reread
supervisor> update
supervisor> start run-mysite.co.uk

This will register our new command, update it and start it. If you are updating an existing command, you only need to run the reread and update. The same could also be accomplished by running the reload command, but this would stop all running processes, update them and then restart them.

Reading Error Logs

When we setup our program you may have noticed the stderr_logfile setting. This lets us tell Supervisor where to output any error generated by the script.

As normal, you can just run the unix tail command on the file.

If you would rather not type in the path to the log file or have to remember its path, you can use Supervisor for this.

Entering the supervisorctl interface, we have the tail command.

supervisor> tail run-mysite.co.uk stderr

Running this command will output the last few lines from the error log file.

Note: You can also add a setting for stdout_logfile that stores all of the scripts output. This could get fairly large fairly quickly.

Monitoring Programs

Now our process is running (or we think it is!) we can check to see its status and uptime. This is done by using the status command within Supervisorctl.

supervisor> status
run-mysite.co.uk                   RUNNING    pid 12345, uptime 0:47:00

You will notice that this gives you the same output as when you first run sudo superisorctl.

Our NodeJS Site

With all of this done, we should now be able to browse to our NodeJS app. Navigating to http://mysite.co.uk:1234. Replace 1234 with the port you have NodeJS running on.

Other Supervisor Uses

As I mentioned earlier, Supervisor can be used for more than just running a NodeJS app. Previously I have used Supervisor to monitor Laravel's php artisan queue:listen command as well as monitor a script that checks for folders created and deleted via ftp/php scripts.

This concludes my first blog post. I hope anyone reading this has found it useful. As usual, feel free to leave any advice or your own findings in the comments.

Resources Used

© 2017. All Rights Reserved.