<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 can be used to speed 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 OS X. 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 ``Connect to Vagrant`` as 
    your project type
(3) Fill in the full path to your Vagrant project directory (which contains your 
    ``Vagrantfile``) and press ``OK``
(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.
(5) Install the remote agent when prompted.

Once this is done, Wing should confirm that the remote agent installation is working.  Then
you can add files and directories and configure your project from the ``Project`` menu.
You will be able to edit, debug, test, search, and manage files on the container, or launch
commands running in the container from Wing Pro's ``OS Commands`` tool.

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``, ``Hostname``, and ``WINGHOME`` under the ``General`` tab, and ``SSH
Port`` and ``Private Key`` under the ``Options`` tab.  Settings these values manually
achieves exactly the same results as using ``New Project``.

The installation process will also add the Vagrant container's SSH host key as a known 
host in ``~/.ssh/known_hosts`` (or in the registry if using PuTTY on Windows).

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. If you want to use private keys with
passwords, you'll need to 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 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.


