<type>how-to</type>
<domain>install</domain>
<id>docker</id>
<title>Using Wing Pro with Docker Compose</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, testing, and debugging of Python code running on 
clusters orchestrated by Docker Compose.</summary>

.. image:: /images/screenshots/wing7-screenshot-dark.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 clusters that are orchestrated by `Docker Compose
<https://docs.docker.com/compose/>`__.

This document describes how configure Wing Pro in order to use Docker Compose
for Python development.

Getting Started
---------------

Before you can work with Docker Compose you will need to download and install it.
See `Install Docker Compose <https://docs.docker.com/compose/install/>`__ for details.

You should also install `Wing Pro <https://wingware.com/downloads/wing-pro>`__ if you
don't already have it.

Configuration Overview
----------------------

To configure Wing to use a Docker Compose cluster, select ``Cluster`` for the ``Python
Executable``, either in the ``New Project`` dialog or ``Project Properties`` (both from
the ``Project`` menu).

In the ``New Project`` dialog, this is found under ``Use Existing Python`` on the second
dialog page, after you have selected your source directory.

In the ``Project Properties`` dialog, it is under the ``Environment`` tab.

After selecting ``Cluster`` for ``Python Executable``, create a new cluster configuration
by pressing the ``New`` button. This displays the cluster configuration dialog. You will
need to enter an identifier to use within Wing and point it at the ``docker-compose.yml``
file for the cluster.

You will also need to select the main service to use as the default place to run your
``Python Shell`` and unit test processes. Note, however, that both the shell and tests can
be configured to run either in synthesized out-of-cluster copies of a cluster service, or
on specific services after the cluster as a whole is launched. This is described in more
detail in Execution Context below.

Once you have created your cluster configuration, submit the ``New Project`` or
``Project Properties`` dialog to complete your project setup.

Controlling the Cluster
-----------------------

You can now control your cluster from Wing's ``Containers`` tool, found in the ``Tools``
menu. The top part of this tool shows the overall status of the cluster and provides
buttons for building, starting, debugging, and stopping your cluster.

The ``Containers`` tool also lists the services in the cluster and their status. 
You can right-click on items in the services list to view their configuration in the
``docker-compose.yml`` file.

When ``Show Synthesized Containers`` is checked in the tool's ``Options`` menu, the
list of services will include out-of-cluster containers that Wing synthesizes and starts,
for example to run the ``Python Shell`` or unit tests.

When the ``Show Console`` item in the ``Options`` menu is checked, the bottom of the tool
shows a console containing the output of the docker-compose commands that Wing is running
behind the scenes.

Debugging the Cluster
---------------------

There are several ways to debug code in a cluster managed by Docker Compose:

**(1)** The most common way to debug a cluster is to select the services that should be
debugged in the services list within the ``Containers`` tool. Then press the ``Debug``
button. Wing launches the cluster in such a way that all Python code run in the selected
services will be debugged.

**(2)** Another way to debug code in a cluster is to first start the cluster as a whole
without debug by pressing ``Start`` in the ``Containers`` tool. Additional processes can
be then started and debugged in-cluster by setting up a ``Named Entry Point`` from the
``Debug`` menu and configuring those to launch code in-cluster. This is done by setting
the ``Python Executable`` in the associated launch configuration to ``Cluster``, selecting
the cluster configuration and service, and checking the ``In-Cluster`` checkbox. See
`Named Entry Points <ref:debug/named-entry-points>`__ for more information.

**(3)** It is also possible to debug code in a synthesized out-of-cluster copy of a
container. This is useful if the container environment as a whole is not needed by that
code, and can be accomplished in the same way as in option (2) above, but by unchecking
the ``In-Cluster`` checkbox.

Execution Context for Other Processes
-------------------------------------

Other processes started by Wing may also be run either on a synthesized out-of-cluster
copy of a selected container service, or on the live service in-cluster after the cluster
as a whole has been started.

Python Shell
............

By default, Wing starts the ``Python Shell`` on a synthesized out-of-cluster copy of
the service you selected as you main service during cluster configuration.  This can be
changed with ``Use Environment`` in the Python Shell's ``Options`` menu.  From here,
a launch configuration may be defined that selects ``Cluster`` for ``Python Executable``
and checks on the ``In-Cluster`` checkbox.

Unit Tests
..........

Unit tests work in a similar way:  The testing environment can be set up with
``Environment`` under the ``Testing`` tab in ``Project Properties``, or in the properties
set by right-clicking on an individual test file.

OS Commands
...........

The ``OS Commands`` tool can also run commands either out-of-cluster or in-cluster. For
command lines, this is done by setting the ``Execution Context`` under the ``Environment``
tab of the OS Command configuration. For Python files, the environment set in the file's
properties is used, or you can define a ``Named Entry Point`` that pairs a Python file
with the desired launch configuration.

For more information on using clusters in Wing, see `Working with Clusters <ref:proj/clusters>`__.

How it Works
------------

Whole-cluster debug is implemented by creating a derived ``docker-compose.yml`` file that
mounts Wing's debugger into the container, and also a ``site-packages/sitecustomize``
directory that imports ``wingdbstub`` in order to initiate debug back to the IDE as soon
as Python starts.

Wing also takes care of all the associated configuration for the debugger, including
establishing the network connection and mapping between local and container side copies
of source files.

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

For more information see:

* `Docker home page <https://www.docker.com/>`__ provides downloads and documentation.

* `Working with Clusters <proj/clusters>`__ for more information on using clusters with Wing Pro.
  
* `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.


