<type>how-to</type>
<domain>install</domain>
<id>vagrant</id>
<title>Using Wing with Vagrant</title>
<date>$Date: 2006-12-28 17:21:05 -0500 (Thu, 28 Dec 2006) $</date>
<product>pro+</product>
<summary>Learn how Wing Pro speeds up development and debugging of Python code running on Vagrant containers.</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 `Vagrant <http://www.vagrantup.com/>`__ containers.  

This document describes how to configure Wing Pro for Vagrant. 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
-------------

This guide assumes you have already installed and started using `Vagrant
<http://www.vagrantup.com/>`__. Wing Pro supports working with Vagrant boxes running Linux
(32-bit or 64-bit) or macOS. Other OS types, such as FreeBSD, won't work.

You will also need to make sure that Python is installed in the Vagrant box. If Python is
not present, Wing Pro's remote agent installation process will fail.

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

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

Creating a Wing Pro project for an existing Vagrant container is easy:

(1) Start your container with ``vagrant up``
(2) Use ``New Project`` from the ``Project`` menu and then select ``Create Configuration`` from
    the ``Host`` menu in the ``New Project`` dialog.  Then select ``Vagrant`` as the ``Remote
    Host Type``
(3) Fill in the full path to your Vagrant project directory (which contains your 
    ``Vagrantfile``) and press ``OK`` to create the remote host configuration
(4) Only on Windows with PuTTY, you will be asked to convert Vagrant's private key into
    a PuTTY key.  To do this, Wing starts ``puttygen`` with the private key already
    loaded into it.  Press ``Save private key`` to save the key as ``private_key.ppk`` 
    in the current directory.  Confirm saving without password (the original also 
    doesn't have a password) and then quit ``puttygen`` to continue the project 
    setup process in Wing.

Once this is done, Wing should install the remote agent and confirm that it
is working. You can now continue through the ``New Project`` dialog to select or create
your source directory on your Vagrant container and select or create the Python
enviromment to use. See `Creating a Project <ref:proj/creating-a-project>`__ for details.

To learn more about Wing Pro's remote development capabilities, see `Remote Hosts
<ref:proj/remote-hosts>`__.

To learn more about Wing Pro's features, take a look at the Tutorial in the ``Help`` menu
or the `Quickstart Guide <ref:howtos/quickstart>`__.

How It Works
------------

Wing uses ``vagrant ssh-config`` to inspect your Vagrant container and fill in the
necessary settings in Wing's project file.

To see the settings that Wing created during ``New Project``, take a look at ``Project
Properties`` from the ``Project`` menu. The ``Python Executable`` was set to point to a
remote host named ``vagrant``. Click on ``Edit`` here or use ``Remote Hosts`` in the
``Project`` menu to access the remote host configuration. The values that Wing sets up
are: ``Identifier`` and ``Hostname`` under the ``General`` tab, ``SSH Port`` and ``Private
Key`` under the ``Options`` tab, and ``Manage SSH Tunnels`` under the ``Advanced`` tqb.
Settings these values manually achieves exactly the same results as using the ``New
Project`` dialog.

Usage Hints
-----------

Synced Folders
..............

As far as Wing is concerned, all files and directories are located in the Vagrant
container and Wing never accesses local copies of the files maintained by Vagrant's
synchronization commands. 

If you need to update your local copies of files for some other reason while working with
Wing, run ``vagrant rsync``, or set up continuous synchronization with ``vagrant
rsync-auto``.

Password-less Private Keys
..........................

Vagrant uses password-less private keys by default. However, Wing can also work with
password-protected private keys. You will be prompted as needed for the passphrase to
unlock your key. Alternatively, you can load the key into the SSH user agent
(``ssh-agent`` or ``pageant`` for PuTTY) and change ``Options > Private Key`` in Wing's
``vagrant`` remote host configuration to ``Use SSH User Agent``.

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

For more information see:

* `Vagrant home page <http://vagrantup.com/>`__ provides downloads and documentation.

* `Remote Python Development <ref:howtos/remote-development>`__ describes how to set up remote development in general.

* `Remote Development <ref:proj/remote-hosts>`__ documents the details of 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.


