<type>how-to</type>
<domain>install</domain>
<id>docker</id>
<title>Using an Existing Docker Container with Wing Pro</title>
<date>$Date: 2006-12-28 17:21:05 -0500 (Thu, 28 Dec 2006) $</date>
<product>pro+</product>
<summary>Learn how to set up a new Wing Pro project that uses an existing Docker container for Python development.</summary>

Creating the Project
--------------------

.. note::

  **Note:** Wing's debugger and Python Shell will not work with any of the ``alpine`` Docker 
  images.  Most other Docker images for Python, including the offiical ``python`` images do work.

To create a new project that uses an existing Docker container, use ``New Project``
in the ``Project`` menu, select your source directory (or choose to create a new one),
and press ``Next``. On the second page, select ``Create New Environment`` and choose
``Docker`` from the drop down menu of environment types. Finally, select ``With Existing
Container`` and enter at least the container image and host-to-container file mapping. The
configuration options are:

**Configuration**

Select the style of configuration to use:  Either an existing already-built Docker image 
ID, or an existing ``Dockerfile``.

**Image ID**

Enter the name of the Docker image to use.  When ``Configuration`` is set to ``Use Image ID``
this selects from those images that have already been built by Docker.  When ``Configuration``
is instead ``Specify Configuration`` this should be the image name defined with ``FROM ... AS``
in the Dockerfile or any valid image name to use for the configuration if ``AS`` is not used.
Existing images are listed in the drop down to the right of the entry field.

**File Mappings**

You must enter at least one file mapping. Each mapping is a pair of directories, one on
the local host and the other on the container. This is the mapping set up for the selected
container image with the ``-v`` command line option for ``docker run`` or using ``COPY``
in the ``Dockerfile``.

**Mapping Type**

This specifies whether the file mappings are made by using ``-v`` with ``docker run`` or
with ``COPY`` in the ``Dockerfile``. In general it's easier to use ``-v`` because the
container does not need to be rebuilt and restarted when host-side files change.

Even when the mapping type is set to use ``COPY``, Wing will establish an internally
defined dynamic mapping with ``-v``, in order to make the debugger and other IDE
functionality available on the container.

**Python Executable**

This selects the Python to run on the container.  In most cases this is the default,
which ``python3`` if it exists or otherwise ``python``.

**Connect Hostname**

This is the host name that the container uses to make a TCP/IP connection to the host
system. In most cases, this is ``host.docker.internal``. On Linux, where ``host``
networking mode is used, set this to ``127.0.0.1`` instead (see Networking on Linux Hosts
below for details).

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

Wing takes the configuration values you enter in the ``New Project`` dialog and 
configures a new Wing project as follows:

1) A new container configuration is created and set as the ``Python Executable``
to use in ``Project Properties``.

2) The mapped directories are added to the project.

3) The ``Python Shell`` is restarted using Python running in the container.

If you didn't create a new source directory along with your project then you will need to
save the project file with ``Save Project`` in the ``Project`` menu.  Otherwise, it is
saved automatically into the new source directory.

Now Wing will run debug processes, unit tests, and the ``Python Shell`` on an instance of
the selected container image. ``OS Commands`` can optionally run commands on the container
or on the local host. This is selected by toggling the ``Run in Container`` option in the
OS Command configuration.

Note that each debug process, each unit test run, and each instance of the ``Python Shell``
creates its own independent instance of the container.

