<type>how-to</type>
<domain>debug</domain>
<id>debugging-web-remote</id>
<title>Remote Web Development</title>
<date>$Date$</date>
<version>$Revision$</version>
<product>pro+</product>
<summary>Learn how to use Wing Pro to debug web code running on a remote host</summary>

.. image:: /images/screenshots/wing7-screenshot-dark.png
  :alt: Wing Screen Shot
  :width: 574
  :height: 423
  :popup: 1

`Wing Pro <https://wingware.com/>`__ is a Python IDE that can be used to develop, test,
and debug websites running on a remote server, VM, or other system where an IDE cannot be
installed. Debugging takes place in the context of the web server or web framework, as
code is invoked by browser page load. Wing provides auto-completion, call tips, find uses,
and many other features that help you work with Python code.

If you do not already have Wing Pro installed, `download it now <https://wingware.com/downloads/wingpro>`__.

This document focuses on how to configure Wing for remote web development. To get started
using Wing as your Python IDE, please refer to the tutorial in Wing's ``Help`` menu or
read the `Quickstart Guide <ref:howtos/quickstart>`__.

Setting up SSH Access
---------------------

Wing Pro's `remote development support <ref:proj/remote-hosts>`__ assumes that you have
already set access to the remote host with SSH.  This can be tested outside of Wing
using ``ssh`` or PuTTY, or you can use Wing's built-in SSH implementation.  See
`Setting up SSH for Remote Development <ref:proj/remote-ssh>`__ for a detailed description
of the available configuration options.  However, in most cases all you will need
to know is the user name and the ip address or host name of the remote system.

Installing the Remote Agent
---------------------------

The next step is to set up a remote host configuration from ``Remote Hosts`` in the
``Project`` menu. Press the ``+`` icon to add a new remote host configuration.

You will need to choose a short identifier that Wing will use to refer to the host and
enter the hostname, which may be a name or an IP address and can be in
``username@hostname`` form if the remote user name does not match the local one. You will
only rarely need to specify any of the other values in a remote host configuration. For
now, leave them blank. For example:

.. image:: debugging-web-remote/remote-host-config.png

Once you submit the dialog for creating the configuration, Wing will try to probe
the remote host and then install the appropriate remote agent.  When the process
completes it should confirm that the remote agent is installed and working as
follows:

.. image:: debugging-web-remote/probe-succeeded.png

Next return to the ``Remote Hosts`` dialog and specify that the remote host 
configuration you've just created should be shared, so that it isn't just stored
in the currently open project:

.. image:: debugging-web-remote/remote-config-shared.png

If something goes wrong during the remote agent installation process, Wing will instead 
show a dialog similar to the following:

.. image:: debugging-web-remote/probe-failed.png

In this case, the output provided may help to diagnose and fix the problem.  Or, for
help contact `support@wingware.com <mailto:support@wingware.com>`__.

Setting up a Project
--------------------

Now it's time to set up a project that accesses your files on the remote host. To do this,
select ``New Project`` in the ``Project`` menu, use the ``Create Blank Project`` option,
and then press ``Create Project``.

You can also set up a remote host from the ``New Project`` dialog, but let's use the
blank project type now so that you will see where the relevant configuration takes
place.

Click ``OK`` to create the project, and then go into ``Project Properties`` from the
``Project`` menu. Set the ``Python Executable`` to ``Remote`` and select the remote host
you've just configured:

.. image:: debugging-web-remote/project-props.png

Next add your files to the project with the ``Add Existing Directory`` item in the
``Project`` menu. Press the ``Browse`` button next to the ``Directory`` field to display a
dialog that browses the file system on the remote host. Go into the directory you want to
add and press ``Select Directory``.

Wing will spend some time scanning the disk and analyzing files but you should already be
able to open and edit source files stored on the remote host from the ``Project`` tool.

Initiating Debug
----------------

This How-To assumes you're going to be launching your web server or web framework from
outside of Wing and want to debug-enable code that is invoked as you browse your
development website. The way Wing does this is by providing a module ``wingdbstub.py``
that you can import to initiate debug.

When you installed the remote agent above, Wing wrote a preconfigured copy of
``wingdbstub.py`` to the remote agent installation directory. By default this is
``~/.wingpro~~MAJOR_VERSION~~/remote-~~FULL_VERSION~~.~~UPDATE~~/wingdbstub.py`` where
``~`` indicates the remote user's home directory. This will vary if you change the
``Installation Directory`` under the ``Advanced`` tab of your remote host configuration
(which is not recommended).

Copy that file to the same directory as your code and add the following to your code
before it reaches anything you'll want to debug:

.. python::

  import wingdbstub
  
Next tell Wing to listen for connections from an externally launched debug process. This
is done by clicking on the bug icon in the lower left of Wing's window and checking on
``Accept Debug Connections``:

.. image:: debugging-web-remote/accept-debug-connections.png

If you hover over the bug icon, Wing shows that it is listening for connections, both on
the local host and on the configured remote host:

.. image:: debugging-web-remote/listen-state.png

**Note:** If you are using Apache or otherwise run your code as a user that is different
from the one used in your remote host configuration, you'll need to adjust permissions on
some files as described in the section ``Managing Permissions`` below.

Debugging Code
..............

Now you can set some breakpoints by clicking on the breakpoint margin to the left of your
code. For example:

.. image:: debugging-web-remote/breakpoint-set.png

Once this is done you should be able to point your browser at a web page that executes
code with a breakpoint, and Wing should stop on it:

.. image:: debugging-web-remote/breakpoint-reached.png

Use `Stack Data <script:show_panel#panel_type="debug-data">`__ to view debug data:

.. image:: debugging-web-remote/stack-data.png

Or just interact on the command line within the current stack frame in the `Debug Console
<script:show_panel#panel_type="debug-console">`__ tool:

.. image:: debugging-web-remote/debug-console.png

Both of these tools are accessible from Wing's ``Tools`` menu.

This technique should work with any web development framework. See `Web Development
How-Tos <ref:howtos/web>`__ for details on using Wing with specific frameworks.

Managing Permissions 
--------------------

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

In this case you must change the disk permissions on the ``Install Dir`` from which you
copied ``wingdbstub.py`` so it can be read by the user that runs your debug process. 
The best way to do this is to create a group that includes both users and use that group
for the directory, for example with ``chgrp -R groupname dirname``.

Then change your copy of ``wingdbstub.py`` by replacing ``~`` with the full path to the
home directory of the user in the remote host configuration. This is needed because ``~``
will expand to a different directory if the code is run as a different user.

You may also want to change the permissions on the debugger security token file
``wingdebugpw`` so that both users can read it, for example with ``chmod 640
wingdebugpw``. The default for this file is to allow only the owner to read it. If this
isn't done, Wing will generate a different debugger security token on the remote host and
will initially reject your debug connection and prompt for you to accept the new security
token. Once that is done, future debug connections will be accepted.

Resources
---------

* `Web Development How-Tos <ref:howtos/web>`__ contains instructions for using
  Wing with specific web development frameworks, such as `Django <ref:howtos/django>`__, 
  `Flask <ref:howtos/flask>`__, `Pyramid <ref:howtos/pyramid>`__, 
  `web2py <ref:howtos/web2py>`__, and others.
  
* `Remote Hosts <ref:proj/remote-hosts>`__ documentation provides details for
  configuring Wing Pro to work with remote hosts.
  
* `Quick Start <ref:howtos/quickstart>`__ provides an introduction to Wing's features.
  
* `Tutorial <ref:intro/tutorial>`__ takes you through Wing's features step by step.

* `Wing Reference Manual <ref:manual>`__ documents Wing in detail.


