<type>how-to</type>
<domain>install</domain>
<id>docker</id>
<title>Creating a New 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 create a new Docker container for Python development with Wing Pro.</summary>

To create a new Docker container along with your new project, 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 ``Create New Container`` and
enter at least the container image and host-to-container file mapping. The configuration
options are:

**Image ID** 

This selects the image ID name to assign to the docker container. It is used within Wing
to refer to the container configuration, by Docker to refer to the container, and is used
as the default new project directory.

**Host-side Project Directory** 

This selects the directory where the new project should be written on the host system.
The directory will contain the generated ``Dockerfile`` and ``requirements.txt``, 
as well as the source directory and other support files.

**Container-side Directory** 

This selects the location on the container where the source directory should be mapped or
copied. The source directory on the host side is always called ``app`` and is created at
the top level of your selected ``Host-side Project Directory``.

**Packages**

This specifies any PyPI packages that should be installed into the new container, either
as a space-separated list of package specifications, or a file that contains one package
specification per line. In either case, the package specifications can be a package name
or ``package:version`` to specify the version to use.

Wing will create ``requirements.txt`` that is stored with the new project and used to make
sure the packages are installed when the container is built. You will be able to add or
change packages on the container later by editing the ``requirements.txt`` file and then
rebuild the container from the ``OS Commands`` tool.

.. note::

  Be sure to read about `Package Security <ref:packages/security>`__.

**Establish Mappings**

When this option is checked (the recommended default), Wing configures the Docker
container so that it is run with your host-side source directory mapped into the container
with the ``-v`` option passed to ``docker run``. This acts like a file share, so that
changes made on the host file system immediately become available within the container,
and changes made within the container are written back to the host file system.

When establishing mappings is disabled, Wing instead uses the ``COPY`` directive in your
``Dockerfile`` to make a copy of your host-side source directory when the Docker container
is built. In this case, the container needs to be rebuilt and restarted whenever a change
is made to your sources. To handle this, Wing sets up the project it creates to
automatically run the build each time code is debugged or executed.

Regardless of hether this is enabled, Wing always establishes an internally defined
dynamic mapping, in order to make the debugger and other IDE functionality available 
on the container.

**Use wingdbstub for Debugging**

When this option is checked, Wing configures the container so that you can initiate
debug from your code using ``import wingdbstub``, rather than starting debug from 
the IDE.  In most cases, this option should be left disabled.  It is useful when
Python cannot be started directly in the container.

**Python Version Specifier**

This option specifies which Python version Wing should install into the Docker
container.  This is placed after the ``FROM: python`` directive in the ``Dockerfile``
that Wing generates.  It can be any of the Python image variants that Docker supports,
including ``3`` for Python 3, ``2`` for Python 2, or a specific version like ``3.8.1``.
If this option is left blank, the latest Python version at build time will be used.
To make your development environment reproducible and uniform, it is best to select
a specific Python version.

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

Once you've created your project, Wing creates the selected host-side directory and
populates it with the following items:

(1) An ``app`` directory is created as the place to put source code for the application.
This directory is either copied into or shared with the container, depending on whether
the ``Establish Mappings`` option was checked. The directory initially contains a
``requirements.txt`` file that specifies which third party packages are needed by your
application. This is passed to ``pip`` during the container build process. If it is
edited, the container will need to be rebuilt (see below). The ``app`` directory also
a starter code file. If the ``Use wingdbstub for Debugging`` option was selected, the file
``wingdbstub.py`` and security token ``wingdebugpw`` will also be placed here and
configured for access to Wing Pro running on the host.

(2) A ``Dockerfile`` is created that tells Docker to use the standard Python container
image and the contents of ``app/requirements.txt`` to set up the container's environment.
The default action of the container, used when ``docker run`` is invoked without arguments,
is to run the application without debug.

(3) The script ``build.sh`` (or ``build.bat`` on Windows) is written to build or rebuild
the container.

Wing also creates and saves a project file into the host-side directory that is configured
to make use of the container. The host-side directory is added to the ``Project`` tool, a
mapping is established between files on the container and host side so that Wing knows
where files are located on each, the ``Python Executable`` is set up to run the
Docker-provided Python, and the project is configured to run the build command
automatically before debugging if not using a dynamic mapping to share files.

Wing then builds the container in the ``Containers`` tool and when that completes saves
the project file to disk and restarts the ``Python Shell`` to contain the Docker-provided
Python. Building the container may take a while if you haven't yet downloaded the
container image or are installing many packages.

Once this completes, you can start debug from the ``Debug`` menu or toolbar. Wing should
reach a breakpoint it has set automatically in the starter code configured with the
project. If you opted to use ``wingdbstub`` to initiate debug, you will need to instead
start the process from outside of Wing or by using ``Execute Current File`` in the
``Debug`` menu. Wing will have added ``import wingdbstub`` to the starter code it
generated, so that debug should start and a breakpoint should be reached.

Whenever ``requirements.txt`` or the ``Dockerfile`` are changed, you will need to rebuild
your container, which can be done by right-clicking on the ``Containers`` tool.



