<type>documentation</type>
<domain>proj</domain>
<id>containers</id>
<title>Individual Containers</title>
<date>$Date: 2010-05-14 11:53:19 -0400 (Fri, 14 May 2010) $</date>
<version>$Revision: 22093 $</version>
<product>pro+</product>

This section describes how to configure Wing when you are using individually managed
containers for your project. In this case, each Wing project specifies a single container
as the default location in which to run Python code launched by the IDE. Additional
containers may also be configured in the project and used for specific files or actions,
for example to debug a client and server running on separate containers, or as a way to
run unit tests on a different container instance.

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

For Docker, Wing provides special support for project creation from the ``New Project``
dialog, either to set up a new Wing project for an existing Docker container, or to create
a new Docker container at the same time as the Wing project. This is described in detail
in `Using Wing Pro with Docker <ref:howtos/docker>`__ and is easier than proceeding with
manual configuration.

For other types of containers, configuration must be done manually, as described below.

Manual Configuration
--------------------

Projects that use a container do so by selecting ``Container`` for the ``Python
Executable`` in ``Project Properties`` and then configuring a container.

A container configuration consists of:

**Identifier** is a unique name used by Wing to refer to this container configuration.
It does not have to be the same as the container system's identification for the
container.

**Type** selects the container system to use for the container.  The available types
are supported through the `container plugin API <ref:plugins/container>`__.

**Configuration** selects the style of configuration use for this container. This may
either use an existing already-build image ID, or specify a container system configuration
file or directory to use for the container.  This field is hidden for container systems
that don't use configuration files.

**Image ID** selects the container image ID to use for the container. When
``Configuration`` was set to ``Use Image ID`` then this specifies the image ID to use.
When ``Configuration`` was set to ``Specify Configuraton`` then it should match the image
ID set by that configuration, if any.  In other cases it may be any image name to use
when creating the container image for this project.  The drop down to the right allows
selecting from the list of known valid image IDs, either all image IDs found on the
system or those defined in the selected container system configuration.

**File Mappings** lists the directories that exist both on the host system and the
container, so that Wing knows which files that are being debugged or tested are identical
to local files. Wing automatically adds its own support directory to this list when the
container is launched, inb order to mount it on the container at
``/wingpro~~MAJOR_VERSION~~``.

**Establish Mappings** controls whether or not Wing sets up the given file mappings
when the container is launched. When enabled, Wing establishes the mappings with file
sharing to the container. When disabled, Wing uses the ``File Mappings`` given above only
to determine which files on the container match local files, and assumes that files are
mapped or copied by the container system configuration and build process. Even when this
is disabled, Wing will establish an internally defined dynamic file mapping that makes the
debugger and other IDE functionality available on the container.

**Python Executable** specifies the Python that should be run on the container.  The
default is to use ``python3`` or ``python`` found on the ``PATH`` on the container.

**Build** selects how to rebuild the container image for this container configuration.
This may either use the container system confuration selected with ``Configuration``
above, or a specified build script.  This field is hidden for container systems that
don't use configuration files and a build process.

**Connect Hostname** is the hostname or IP address that can be used on the container to
establish a TCP/IP connection back to the host system where Wing is running. This
capability is used to set up remote inspection of the container, and to run unit tests,
debug processes, the ``Python Shell``, and OS commands on the container. Docker version
18.03 or later running on Windows and macOS defines ``host.docker.internal`` for this
purpose. In other cases, the IP address of the host system may need to be determined
manually.  This field is hidden for container systems that support automatically
determining the container instance IP address.

**Port Forwarding** identifies network ports that should be forwarded from the host system
to the container. This is used to allow access to network services, such as a web server,
that are running on the container. Containers may also specify port mappings at build
time, but in some cases (such as with Docker Desktop on macOS) this is not possible.
Note that services running on the container must listen on all interfaces (0.0.0.0)
and not localhost (127.0.0.1) in order for port forwarding from the host to container
to work properly.

**Inherit Project Environment** tells Wing to set environment variables defined in
``Project Properties`` into the container environment. This is off by default since in
most cases containers define their own environment. When any environment variables are
defined in ``Project Properties``, Wing will prompt to explain how these will be treated
in the container. This prompt can be disabled from the dialog or with the `Project >
Containers > Show Environment Warning
<script:show_preferences_gui#prefname="main.show-container-env-warning">`__ preference.

All container configurations are made available in the container-manager accessed with
``Containers`` in the ``Project`` menu.

Container Instance Management
-----------------------------

When individual containers are configured like this, a single instance of each container is
started and reused to run all debug processes, unit tests, the ``Python Shell``, commands
run on the container by ``OS Commands``, and processes used to inspect Python and files on
that container. If the container instance terminates unexpectedly, it is restarted
automatically as needed.

The instance may also be restarted automatically when Wing's container configuration is
changed or when the image used for the container is rebuilt or changes. The action taken
in these two cases can be controlled with the following preferences on the `Project >
Containers <script:show_preferences_gui#prefname="main.show-container-config-warning">`__
preferences page:

**Warn Before Container Configuration** controls whether Wing warns before it allows any
changes to a container configuration for an actively running container.

**Notify Container Configuration Change** controls whether Wing notifies that a container
instance has been restarted as a result of a change to the container configuration in Wing
Pro.

**When Container Image Changes** selects the action to take when Wing detects that a
running container instance's image has been rebuilt. The options are to automatically
restart the container instance, to leave the instance running with the old image, or to
display a dialog to prompt for action.

Whenever a container instance restarts, for any reason, all debug processes, unit tests,
and other commands running on the container will be terminated and the ``Python Shell``
will be restarted.

Multiple Containers
-------------------

Although Wing expects a single container to be specified as the main ``Python Executable``
in ``Project Properties``, and this is used to determine Python version and environment
for your project, it is possible to define several containers in a project and use them to
launch specific files, unit tests, OS Commands, or the ``Python Shell``. 

This is done by creating multiple container configurations from ``Containers`` in the
``Project`` menu, and then defining one or more `launch configurations
<ref:proj/launch-configs>`__ that reference the containers through their ``Python
Executable`` property. Launch configurations can be created from ``Launch Configurations``
in the ``Project`` menu and may then be used in:

**File Properties**, accessed by context menu from the editor or ``Project`` tool, can
select a particular launch configuration to use for an individual file. This is done by
setting ``Environment`` under the ``Debug/Execute`` tab to ``Use Selected Launch
Configuration`` and choosing the desired launch configuration. The file is then executed
and debugged on the selected container. Note that this does require that the file is
mapped onto the container in one of the mappings specified in the container configuration's
``File Mappings`` field.

**Unit Tests** may be run on a selected container by setting the ``Environment`` under the
``Testing`` tab in ``Project Properties``, or in a file's ``File Properties``, to affect
only the environment used when running unit tests.

**OS Commands** may be run on a different container by setting the ``Execution Context``
under the ``Environment`` tab for ``Command Line`` style OS commands, by setting the
``File Properties`` on the file used for ``Python File`` style OS commands, or selecting a
launch configuration for ``Named Entry Point`` style OS commands.

**Python Shell** processes may be configured to run on a particular container by selecting a
launch configuration under ``Use Environment`` in the ``Python Shell``'s ``Options`` menu.

The same technique may be used to cause files, unit tests, OS Commands, or the ``Python Shell``
to be launched on the local host rather than in any container, by selecting a launch
configuration with ``Python Executable`` set to ``Default`` or a specified ``Command Line``
or ``Activated Env``.

Container-Only Files
--------------------

For files that are stored only on the container, such as the Python standard libraries and
the contents of ``site-packages``, Wing launches a container instance, fetches the files,
analyzes them, and displays them read-only.

