<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/>`__ can connect securely to a remote host, VM, or
container, in order to work with files on the remote system 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 macOS 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 need to be able to connect to your
remote system using SSH. This can be tested outside of Wing with ``ssh`` on Linux and
macOS or either OpenSSH (provided by ``Cygwin``, ``Git Bash``, or similar) or ``PuTTY`` on
Windows. If you don't have either ``ssh`` or PuTTY, Wing falls back to using its own
built-in SSH implementation. See `Setting up SSH for Remote Development
<ref:proj/remote-ssh>`__ for a detailed description of all 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.

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

To set up a new project that works with a remote host, select ``New Project`` from the
``Project`` menu and choose ``Create New Configuration`` from the ``Host`` menu in the
``New Project`` dialog. 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 Linux system on a local network
from macOS:

.. image:: remote-development/new-project.png
  
The press ``OK`` to create the remote host configuration and install the remote agent
if necessary.

If the remote agent needed to be installed or upgraded then Wing will briefly show a status dialog
during installation and inspection of the remote system, followed by a confirmation dialog:

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

Close this dialog and you will see that the new remote host configuration has been
selected for your new project:

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

You can now continue by selecting or creating your source directory and selecting or
creating a Python environment to use with the project.  See `Creating a Project
<ref:proj/creating-a-project>`__ for details on the configuration options.

After you press the ``Create Project`` button in the ``New Project`` dialog, 
Wing will set up your project.  You can then save the project to local disk
with ``Save Project`` in the ``Project`` menu.

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

If you bring up the ``Python Shell`` from the ``Tools`` menu, you should be able to
interact with the Python environment you selected on your remote host. For example, here
is Python running remotely on a CentOS 6 system from Wing on macOS:

.. 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 inside your
project file. 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``. 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 macOS 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.
