Upsun User Documentation
Edit page

Debugging

Back to home

On this page

Try Upsun for 15 days
After that, enjoy the same, game-changing Upsun features for less with the First Project Incentive!¹ A monthly $19 perk!
¹Terms and conditions apply
Activate your 15-day trial

Effectively debugging web apps takes effort, especially when an HTTP request goes through multiple layers before reaching your web app. Follow the steps below to debug a specific app.

You can choose to debug in an environment deployed to Upsun or with your app running locally but connected to deployed services. In either case, make sure to debug in a preview environment.

For more general information, see how to troubleshoot development.

1. Create a new environment Anchor to this heading

Start by creating a new environment completely isolated from production but with the same data for debugging:

upsun branch debug-branch

2. Get access Anchor to this heading

Access your app container via SSH:

upsun ssh

To access deployed apps and services, open tunnels to everything your app has relationships with:

upsun tunnel:open

In the same terminal, set the relevant environment variables:

export PLATFORM_RELATIONSHIPS="$(upsun tunnel:info --encode)"
export PORT=8888

3. Run your app in inspect mode Anchor to this heading

Stop the current process and restart it in inspect mode:

sv stop app
node --inspect <START_FILE>

In the same terminal as the previous step, run the following command:

node --inspect <START_FILE>

Replace <START_FILE> with the file defined for your app’s start command.

You get output something like this:

Debugger listening on ws://127.0.0.1:9229/10701e5d-d627-4180-a967-d47a924c93c0
For help, see: https://nodejs.org/en/docs/inspector
Listening on port 8888

4. (If debugging remotely) Forward the debugger port locally Anchor to this heading

In another terminal, create an SSH tunnel that forwards to the 9229 port:

ssh -N -L 9229:localhost:9229 $(upsun ssh --pipe)

5. Connect the debugger Anchor to this heading

You can now connect the debugger as if you were debugging a local application. See examples with some common tools:

Go to chrome://inspect. Find your running app under the Remote Target list. Click inspect to start the debugger.

Use the Node.js: Attach debugger option.

If you haven’t created the option:

  1. On the Run and Debug tab, click create a launch.json file.
  2. Select Node.js as the environment.
  3. In the configurations array, start IntelliSense (usually ctrl+space).
  4. Select Node.js: Attach.
  5. Make sure the port is the same as in step 4 above.

Once you have the option:

In the Run and Debug tab, select Attach from the menu and click Start Debugging (the green arrow).

See more on Node.js debugging in Visual Studio Code.

Now when you load the site at your deployed URL (if debugging remote) or localhost (if debugging locally), the local debugger you’ve attached is called.

Set breakpoints:

In the JavaScript files from your remote site: On the Run and Debug tab under Loaded Scripts find Attach: Remote Process > /app.
Directly in your source files.

Other issues Anchor to this heading

pm2 process manager blocks other processes Anchor to this heading

If you’re using the pm2 process manager to start your app from a script, you might find it daemonizes itself and blocks other processes (such as backups) by constantly respawning. This may happen even if you use the --no-daemon flag.

Instead of using a script, call pm2 start directly in your start command.

Is this page helpful?