<type>how-to</type>
<domain>install</domain>
<id>wsl</id>
<title>Using Wing Pro with AWS</title>
<date>$Date: 2006-12-28 17:21:05 -0500 (Thu, 28 Dec 2006) $</date>
<product>pro+</product>
<summary>Learn how to use Wing Pro to remotely develop, test, and debug Python code 
running on an AWS instance.</summary>

.. image:: /images/screenshots/wing7-screenshot-linen.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 Python code running on `Amazon Web Services <https://aws.amazon.com/>`__ (AWS).

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

Prerequisites
-------------

You will need an AWS instance that has Python installed on it, is running 32-bit or 64-bit
Intel Linux, and that you can connect to with SSH. You will need the following in order to
configure Wing Pro to use your AWS instance:

**(1)** The user name and static IP address or DNS name used to connect to the AWS
instance. Amazon Lightsail typically uses an IP address while EC2 and other variants of
AWS may provide a DNS name as well. The static IP address will work in any case.

**(2)** The SSH key pair in a ``*.pem`` file, as downloaded from AWS.

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

Setting up AWS
--------------

*If you already have an AWS instance to work with, you can skip this section.*

Otherwise, `Amazon Lightsail <https://aws.amazon.com/lightsail/>`__ is the easiest way to
get an AWS instance, in about 5 minutes. You will need to set up an account. Then create a
``Linux/Unix`` instance, selecting the ``OS Only`` option and the most recent ``Ubuntu``
or any other Intel Linux with Python 2 or 3 on it.

While setting up your instance, you can download your SSH key pair under the AWS ``SSH key
pair manager``. You'll need this on your local machine, where Wing is running, in order to
be able to connect to the instance.

After the instance is created, it will remain in ``pending`` state for a minute or so.
Once it is up and running, create a static IP address under the ``Network`` tab in the
AWS Lightsail management area and attach it to your instance.

At this point you have all that is needed to start using Wing Pro with AWS: (1) The
SSH key pair that you downloaded, and (2) the user name and IP address, which are 
shown on the Lightsail instance management page.

Testing the SSH Connection
--------------------------

Before trying to use your new instance from Wing Pro, you may want to first try to connect
using ``ssh`` or PuTTY's ``plink.exe`` on the command line, to make sure your
configuration is working. This is not a requirement, however, since you can also connect
to AWS using Wing's built-in SSH implementation.

**OpenSSH**

On Linux or macOS using ``ssh``, you need to make your ``*.pem`` SSH key pair file
readable only by the user running Wing, for example with::

  chmod 600 aws.pem
  
Otherwise, ``ssh`` will reject it as potentially compromised.
  
Once that is done, try connecting as follows, substituting the actual path to your
downloaded SSH key pair and your instance's username and IP address or DNS name::

  ssh -i /path/to/mykey.pem ubuntu@11.22.33.44

You will be asked to add the instance's identity to your known hosts file, which you
should do by typing ``yes``. If this is not done, ``ssh`` will fail to connect and Wing
will also not be able to connect to the instance.

**PuTTY**

With PuTTY on Windows, you will need to first convert the SSH key to a format that
PuTTY can use. This is done by launching ``puttygen``, pressing the ``Load`` button to
read the ``*.pem`` SSH key file you downloaded from the AWS management site, and then
using ``Save Private Key`` to write a ``*.ppk`` file.

Then you invoke ``plink.exe`` to connect to the AWS instance as follows, substituting in
the actual path to your downloaded SSH key pair and the correct username and IP address or
DNS name for the AWS instance::

  plink.exe -i C:\path\to\mykey.ppk ubuntu@11.22.33.44
  
You will be asked to accept the AWS instance's identity the first time you connect, and
this must be done before Wing's remote development support will work with the AWS
instance.

**Built-in SSH Implementation**

If you don't have ``ssh`` or PuTTY, you can also just use Wing's built-in SSH
implementation.  You will need to know the full path to your AWS ``.pem`` private
key file and also the username and host's IP address.  Once you have these,
proceed to the next section to configure your connection to AWS in Wing.

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

Now you're ready to create a project in Wing Pro. This is done with ``New Project`` from
the ``Project`` menu. From the ``Host`` menu at the top of the first page in the ``New
Project`` dialog, select ``Create Configuration``. 

This displays the ``New Remote Host`` dialog where you can configure Wing to connect to
AWS. Select ``AWS`` for the ``Remote Host Type``. Then enter an identifier for the remote
host (any short string to identify it in Wing's UI) and the user name and IP address or
DNS name used to connect to the AWS instance.

In most cases ``Python Executable`` should be ``Use default``, which first tries
``python3`` and then ``python``. If Python is not on the ``PATH`` on your AWS instance or
you want to specify a particular Python executable or activate a virtual environment, you
can do this here.

You will also need to point Wing at the SSH key file you downloaded from AWS earlier.
This is done under the ``Options`` tab of the ``New Project`` dialog, using the 
``Private Key`` field.  Select ``Use private key file`` and enter the full path to your
downloaded SSH key.

Pressing ``OK`` in the ``New Remote Host`` dialog will create the remote host configuration,
so Wing can already connect to your AWS instance.  Form here you can select or create your source
directory on the AWS instance, and choose or create the Python environment to use.  See
`Creating a Project <ref:proj/creating-a-project>`__ for details.

After pressing ``Create Project`` in the ``New Project`` dialog, Wing will configured a
new untitled project. You can save it to local disk from the ``Project`` menu.

Testing a Hello World
---------------------

To try out a simple example of editing and debugging code on the remote AWS instance,
create a file ``helloworld.py`` temporarily on the instance.  This is done by right-clicking
on one of the directories in the ``Project`` tool in Wing Pro and selecting ``Create New File``.
Enter the file name (in some key bindings this is in the data entry area at the bottom of 
Wing's window) and then type or paste the following into the new file:

.. python::

  import time
  print("Hello World! {}".format(time.time()))

After saving the file, set a breakpoint on the second line by clicking on the leftmost
margin in the editor. Then select ``Start/Continue`` from the ``Debug`` menu to start
debug, or use the green play icon |play| in the toolbar.

.. |play| image:: icon:wingide-debug-continue
  :class: inline-image

There is a slight delay to get the process started, depending on your network distance
from the AWS instance, but then you should see Wing stop on the breakpoint.  Although
there's not much to see in this context, you can check that it's working by entering
the following into the ``Debug Console`` tool:

.. python::

  time.time()

Once you continue debugging, the process will exit and print its "Hello World" message 
to Wing's ``Debug I/O`` tool.

Related Documents
-----------------

For more information see:

* `Amazon Web Services (AWS) <https://aws.amazon.com/>`__ provides documentation and
  links for creating an AWS account and instance.
  
* `Remote Hosts <ref:proj/remote-hosts>`__ for details on configuring remote development.

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

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

