<type>how-to</type>
<domain>install</domain>
<id>docker</id>
<title>Using Wing Pro with Docker</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 Docker containers.</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 `Docker <https://www.docker.com/>`__ containers.  

This document describes how to create a new Wing Pro project that uses a Docker container
for Python development.

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

Before you can work with Docker you will need to download and install it.

**On Windows and macOS**, downloading Docker Desktop from the `Docker
<https://www.docker.com/>`__ website is the easiest way to install it. Be sure to launch
the Docker Desktop after installation, so that the daemon is started.

**On most Linux distributions**, Docker CE (the free community edition) can be installed
with the ``docker-engine`` package as `described here
<https://runnable.com/docker/install-docker-on-linux>`__.

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

**Important:** You will need to add the installation directory of Wing Pro to the ``File
Sharing`` list under ``Settings > Resources`` in Docker Desktop. This tells Docker to
allow use of the ``-v`` flag to create file shares that map Wing into the container, so
that it can access and debug code on the container. You need to do this even if you aren't
using ``-v`` yourself, because Wing does it internally. This can be confusing because
Docker does not print any error message if a ``-v`` is disallowed. It just skips that file
share. However, this step is only needed if you installed Wing into a location that is not
already listed for ``File Sharing``. For example, if you installed Wing somewhere under
your home directory and ``/Users`` (Windows and macOS) or ``/home`` (Linux) is already in
the ``File Sharing`` list then Docker already allows mapping all sub-directories of those
and you don't need to add to the configuration.

Overview of Docker
------------------

Docker provides a light-weight form of virtualization that serves to isolate running code
from the host system, both for security and so that a replicable controlled environment
can be created for developing and running applications. 

Docker containers may be used to deploy code into production, and this may
include spinning up new container instances on the fly to balance load or
service incoming requests in a securely isolated environment.

Docker works by making use of standard preconfigured images that contain particular
technologies pre-installed on either a Linux or Windows OS. These images are managed in a
curated library and downloaded automatically, as needed to build your containers.

Each container may contain copies of files from the host system, either placed when the
container is built or provided by file sharing as the container runs. Containers do not
have any access to the host file system unless file sharing is configured, and then they
can only write into the shared areas.

Containers can, however, access the host system through a network connection, which is
what makes it possible to debug code running within a container from a copy of Wing Pro
running on the host system.  It is also possible to map network ports from the host system
into the container, to facilitate development of network services and websites.

Containers are typically short-lived, persisting for the duration of one run of an
application or for the purpose of performing a single computation. They are built, run,
and then discarded after optionally retaining some state information or the result of the
computation through a file share or network connection. Containers used in this way are
often orchestrated into a larger system using Docker Compose or Kubernetes. This is how
Docker can automate deploying, load-balancing, and management of containerized
applications.

However, how to approach container life-cycle is up to the user. Other containers may be
run many times, or over a long period of time, using data shared with the host system.
Thus, containers may either be small ephemeral components of an application, or they may
act more like a traditional virtual machine or server.

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

Wing Pro offers a number of ways to work with Docker containers:

(1) **Use An Existing Container** -- Wing Pro can configure a new project to use an
existing Docker container. This approach requires specifying at least the container image
to use and the host-container file mapping used by that container. Wing works with files
stored on the local disk and launches debug processes, the Python Shell, unit tests, and
optionally OS Commands within the container environment using the container's mapped
copies of those files.

(2) **Create a New Container** -- Wing Pro can also create and configure a new Docker
container. This approach creates the ``Dockerfile`` and a working starter application,
configures a Wing Pro project file to use it, and automatically builds the container. This
case also works with files on the local disk and runs debug and other processes on the
container.  When Wing creates a new Docker container, it uses the standard preconfigured
'python' container image with the selected Python version and packages installed 
by ``pip``.

(3) **Remote Development via SSH** -- For containers that run OpenSSH and act more like a
longer-lived virtual machine or server, Wing can connect to the container is if it were a
remote host. This allows working directly with files on the container, rather than using
local copies of the files.

These are each described in the following sub-sections of this How-To.

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

For more information see:

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

* `Working with Containers and Clusters <proj/container-intro>`__ for more information
  on using containers in 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.


