<type>webpage</type>
<domain>howto</domain>
<id>remote-development</id>
<title>Remote Python Development</title>
<date>2017-01-17</date>
<version>$Revision: 13666 $</version>
<product>pro+</product>
<summary>Wing Pro makes it easy work with Python code stored on a remote host.  The IDE can edit, test, debug, search, and manage files as if they were stored on the same machine as the IDE.</summary>

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

`Wing Pro <https://wingware.com/>`__ has the ability to connect to a remote host, VM, or
container through a secure SSH tunnel, in order to work with files stored remotely in the
same way that Wing supports working with files on your local system. Editing, debugging,
testing, searching, version control, Python Shell, OS Commands, and other features all
work with remote systems.

Currently, Wing can work remotely to OS X and Intel or ARM Linux systems. This includes
any PEP 513 compatible Intel Linux system and ARM systems like Raspberry Pi and Jolla
phone. We are still expanding the range of remote systems that we support. For a detailed
list of the remote host types supported in the current release, please see `Supported
Platforms <ref:install/supported-platforms>`__. If you try a device and cannot get it
working, don't hesitate to email `support@wingware.com <mailto:support@wingware.com>`__
for help.

Configuration
-------------

Before you can set up remote development in Wing, you first need to have an SSH key pair
and set up password-less (SSH key authenticated) remote access to your target host using
``ssh`` on Linux and OS X or either OpenSSH (provided by ``Cygwin``, ``Git Bash``, or
similar) or ``PuTTY`` on Windows. If you don't already have this, please refer to `SSH
Setup Details <ref:proj/ssh-setup-details>`__ in Wing's documentation.

Once you have password-less SSH access working outside of Wing, in most cases Wing will
automatically find and use your SSH configuration. If it fails to do that in the steps
that follow, you may need to set the ``Network > SSH Executable`` preference to the full
path to ``ssh``, ``ssh.exe``, or PuTTY's ``plink.exe``, and/or ensure that Wing can access
the SSH user agent. See `Setting up SSH for Remote Development <ref:proj/remote-ssh>`__
for detailed instructions.

Creating a Project
------------------

To set up a new project that works with a remote host, select ``New Project`` from the
``Project`` menu and choose ``Connect to Remote Host (via SSH)`` as the project type. Then
enter an ``Identifier`` to use for the remote host and the ```Host Name`` or ip address
(optionally in the form ``username@hostname``). You only need to specify ``Python
Executable`` if ``python`` is not on the ``PATH`` on your selected remote host or you want
to select one of several Python installations.

For example, here is a configuration to access a RedHat Linux system on a local network
from OS X:

.. image:: remote-development/new-project.png
  
To keep things simple, leave ``Store Project File on Remote Host`` unchecked and then
press ``OK``. This will create the project and a remote host configuration, and will try
to contact the remote agent. Wing will install the remote agent if necessary:

.. image:: remote-development/install-agent.png

If installation was necessary and succeeded, you will see a confirmation dialog as follows:

.. image:: remote-development/install-success.png

Close this dialog and you will see a confirmation that the project was created
successfully:

.. image:: remote-development/confirmation.png

In this case, just select ``Save Later``.

Using Your Project
------------------

Now you can right-click on the ``Project`` tool, accessed from the ``Tools`` menu, and
select ``Add Existing Directory`` to add a directory containing your source code. Press
the ``Browse`` button in the ``Add Directory`` dialog to browse files on the remote
system. Afterward, save the project to local disk with ``Save Project`` in the ``Project``
menu.

If you restart the ``Python Shell`` from its ``Options`` menu, Wing will start the shell
on the remote host. For example, here is Python running remotely on a CentOS 6 system from
Wing on OS X:

.. image:: remote-development/python-shell.png

To debug, open a file from the directory you added to the project and select
``Start/Continue`` in the ``Debug`` menu. Wing launches the file in the debugger on the
remote host and will reach breakpoints and exceptions. Debugging a remote file works the
same way as for local files. You can use the ``Debug Console``, ``Stack Data``, ``Watch``
and other tools to inspect and debug your code.

.. image:: remote-development/debugging.png

Other tools, including the ``Testing`` tool for unit testing, the version control
integrations, and ``OS Commands`` for executing non-Python command lines all work on the
remote host.

Details
-------

The remote host configuration you created along with your project is stored within the
project file in this case, because you stored the project on local disk. You can view and
edit the configuration, or create other remote host configurations, from ``Remote Hosts``
in the ``Project`` menu:

.. image:: remote-development/remote-hosts.png

It is possible to set up multiple remote host configurations for one project, but the
project's ``Python Executable`` in ``Project Properties`` (from the ``Project`` menu) can
only point to one of the remote hosts, and that is where the ``Python Shell`` and debug
processes are run. Changing the ``Python Executable`` is what determines whether a project
points to local disk or some remote system. Here are the ``Project Properties`` that were
set up automatically in the project we created above:

.. image:: remote-development/project-properties.png

**Remotely Stored Projects**

In this example, we stored the project file on local disk, but project files can also be
stored on the remote host. In that case, the remote host configuration needs to be checked
as ``Shared``, as for remote host ``vagrant`` in the ``Manage Remote Hosts`` dialog above.
This stores the remote host configuration locally so that it can be used to access the
remote project later with ``Open Remote Project`` from the ``Project`` menu.

You can also use this feature to remotely open a regular locally created Wing project.

**Remote Display with X11**

To work with code that displays a user interface, you can forward X11 display to occur on
the machine where Wing is running. This is done by checking the ``Forward X11`` option in
your remote host configuration, under the ``Options`` tab. 

Unless Wing is running on Linux, you will also need to install and run an X11 server on
the machine where Wing is runing, for example ``XQuartz`` on OS X or ``MobaXTerm`` on
Windows.

**Further Reading**

For more information see:

* `Remote Hosts <ref:proj/remote-hosts>`__ for more detailed instructions and advanced 
  configuration options.

* `Remote Web Development <ref:howtos/debugging-web-remote>`__ describes how to
  set up remote development where the debug process is launched from outside of the
  IDE, for example by a web server or framework.

* `Quickstart Guide <ref:howtos/quickstart>`__ contains additional basic information
  about getting started with Wing.
  
* `Tutorial <ref:intro/tutorial>`__ provides a gentler introduction to Wing's features.

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

Please don't hesitate to contact `support@wingware.com <mailto:support@wingware.com>`__ if
you need help getting remote development working.
