Node.js debugging
on Passenger + Nginx

Passenger is compatible with Node.js debugging tools such as the builtin Node.js debugger and node-inspector.

The builtin Node.js debugger is a simple terminal-based debugger that accepts terminal commands, while node-inspector is a GUI based on the Blink Developer Tools. This tutorial teaches you how to use those tools with Passenger.

The idea is that you start a Node.js app with a debugging port enabled. You then attach the debugger interface to the debugging port.

Table of contents

Step 1: write a Node.js debugging wrapper script

The goal of this step is to ensure that Passenger starts Node.js application processes with the correct debugging parameters. This is achieved by making a wrapper script.

Create a file /usr/local/bin/node-passenger-debug-wrapper containing:

#!/bin/sh

# Tells Node.js to open a debugging port on 7500.
# Feel free to change the number to anything you like.
exec /path-to-nodejs-or-iojs-binary --debug=7500 "$@"

Make sure this wrapper script is executable:

sudo chmod +x /usr/local/bin/node-passenger-debug-wrapper

Step 2: configuring Passenger

You must configure Passenger to do two things:

Ensure that Passenger uses the wrapper script to start Node.js apps.
Ensure that Passenger only starts 1 process for your application. It is currently not possible to debug apps that have multiple processes.

Nginx configuration:

# Use debug wrapper script.
passenger_nodejs /usr/local/bin/node-passenger-debug-wrapper;
# Ensure that min_instances is set to 1, not a higher number.
passenger_min_instances 1;

Restart Nginx to have the change applied.

Step 3: start app, attach the debugger

Make a request to your app so that Passenger starts it:

$ curl http://www.yourapp.com/

You can now attach a debugger interface to your app.

Node.js builtin debugger

To use the Node.js builtin debugger, run node debug localhost:7500. It will drop you in a debugging prompt:

$ node debug localhost:7500
connecting to localhost:7500 ... ok
debug>

At this point, you cannot debug the application yet. The app must be paused at a point where it is executing Javascript. So instruct the debugger to pause the app using the pause command.

debug> pause

When you have executed this command, two things can happen. The first thing is that you immediately see the source line where the app is paused at, like this:

break in net.js:1301
 1299 };
 1300
>1301 function onconnection(err, clientHandle) {
 1302   var handle = this;
 1303   var self = handle.owner;

The second thing that may happen is that the pause command doesn't appear to have any effect. This can happen if the app is currently waiting for an I/O event instead of executing Javascript. In this case, you must wake the app up by making a request to it:

$ curl http://www.yourapp.com/

If you go back to the debugger, you should see that it has paused the app at a Javascript source line.

Node-inspector

Install node-inspector if you haven't already:

$ npm install -g node-inspector

Then start node-inspector, telling it where the app's debugging port lies:

$ node-inspector --debug-port 7500
Node Inspector v0.10.1
Visit http://127.0.0.1:8080/debug?ws=127.0.0.1:8080&port=7500 to start debugging.

Visit the URL that node-inspector tells you to visit. You should see the debugging interface.

Conclusion

Debugging Node.js apps on Passenger requires just a few config options. For future versions, we are looking into introducing features that make invoking debuggers even easier.

Node.js debugging on Passenger + Nginx