Debugging Externally Launched Remote Code

Index of All Documentation » Wing Pro Reference Manual » Advanced Debugging Topics » Debugging Externally Launched Code »

This section describes how to debug code launched on a remote host. These instructions are needed only if you cannot launch your code from Wing. For example, if your code runs under a web server or as an embedded script in a larger application, then it cannot be started by Wing.

The following instructions rely on Wing Pro's Remote Hosts feature to display and edit remote files. If you cannot use that feature for some reason, follow the instructions for Manually Configured Remote Debugging instead.

  • First set up a remote host configuration as described in Remote Hosts, install the remote agent on the remote host when prompted, and create a project that sets the Python Executable in Project Properties to the remote host and includes your remote source code. Before continuing, check that you can open remote files in Wing's editor.
  • Copy from the directory where you installed the remote agent (specified as WINGHOME in the remote host configuration) into the same directory as your debug program.
  • At the point where you want debugging to begin, insert the following into your code: import wingdbstub. If you are debugging code in an embedded Python instance, see the notes in Debugging Embedded Python Code. If you are debugging code running as a different user than the one in your remote host configuration, see Managing Permissions below.
  • Make sure the Wing preference Accept Debug Connections is turned on, to allow connection from external processes. Once this is enabled, Wing will start listening for connections from the remote host you configured in your project.
  • Set any required breakpoints in your Python source code.
  • Initiate the debug program from outside Wing in a way that causes it to import wingdbstub and reach a breakpoint or exception.

You should now see the status indicator in the lower left of the main Wing window change to yellow, red, or green, as described in Debugger Status. If no breakpoint or exception is reached, the program will run to completion, or you can use the Pause command in the Debug menu.

Managing Permissions

If your code is running as a different user than the one specified in your remote host configuration, as would be the case if running under Apache or another web server, then you will need to make some additional changes so that remote debuging will work. For example, your remote host configuration may set``Host Name`` to devel@ while the code is actually run by the user apache.

In this case, Wing will not accept the debug connection because the security token from the user running the code does not match what Wing is expecting from the way it installed and configured the remote agent.

To solve this, go into the WINGHOME where you installed the remote agent and change the permissions of the file wingdebugpw so that the user running the code can also read it. For example, if both your users are members of the group webdev then you can do this:

chgrp webdev wingdebugpw

A less secure solution is just to change the permissions of this file so everyone can read it:

chmod 644 wingdebugpw

The disadvantage of this approach is that other users could potentially use the contents of this file to connect to your instance of Wing against your will.

Changing Remote Debug Port

Remote debugging is implemented by listening locally and establishing a reverse SSH tunnel to the remote host configured in your project.

By default Wing will listen on port 50050 on the remote host. Note that this is different than the default port used to listen on the local host, which is 50005. This is done to prevent the remote agent from interfering with a local copy of Wing, when both are in use.

If this conflicts with another service on the remote host, or if there are multiple remote debug connections to a single host, you will need to change this port number to be unique for each developer. To do this, edit the Debug Port property of your remote host configuration and track this change in kWingHostPort in your copy of on the remote host.

You can verify that Wing is listening on the remote host and inspect the port number being used by hovering your mouse over the bug icon in the lower left of Wing's main window.

Debugging on Multiple Remote Hosts

Wing listens locally and on the remote host specified in Python Executable in Project Properties. To listen on multiple hosts at once, use separate projects and multiple instances of Wing. You can open additional instances of Wing by adding --new to the command line.

Diagnosing Problems

If you have problems making this work, try setting kLogFile variable in to log diagnostic information.