<type>how-to</type>
<domain>install</domain>
<id>lxc</id>
<title>Using Wing Pro with LXC/LXD Containers</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 LXC/LXD 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 LXC Linux containers hosted by
`LXD <https://linuxcontainers.org/lxd/introduction/>`__.

This document describes how to create a new Wing Pro project for Python development
on a Linux container.

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

Before you can work with Linux containers in Wing, you will need to `install
and configure LXD <https://linuxcontainers.org/lxd/getting-started-cli/>`__.

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

Overview of LXC/LXD
-------------------

LXC implements Linux containers, which provide a light-weight form of
virtualization that is useful for its security, standardization of runtime
environment, and ability to support scalable deployment. LXD is the
next-generation toolset for controlling LXC containers.

LXC/LXD use standard preconfigured container images that are managed in a
curated library and downloaded automatically, as needed to run your
containers. Each container may contain copies of files from the host system,
either copied into place 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.

Some LXC/LXD containers, depending on configuration, can access the host
system and/or other containers in a cluster through a network connection. It
is also possible to map network ports from the host system into the
container, to facilitate development of network services and websites.

Wing Pro supports only the newer LXD command line interface. It requires that
the container has network access to the host system, which is enabled by
default when a container is created. The container must also have Python
installed on it, which most Linux systems do.

Creating a Container
--------------------

You will first need to create a container instance, as follows::

  lxc launch ubuntu:20.04 demo
  
You can replace ``ubuntu:20.04`` with any image that includes Python.  Type the
following to see a list of all available images::

  lxc image list images:  

The name ``demo`` may also be replaced, with any other name for the new container 
instance.

Configuring Your Project
------------------------

To set up a Wing project that uses your LXD container, select ``New Project`` from
the ``Project`` menu, select ``Create Blank Project``, and press the ``Create Project``
button.

After your project has been created, select ``Project Properties`` from the confirmation
dialog or ``Project`` menu.  Then set ``Python Executable`` to ``Container`` and
press ``New`` to create a new container configuration.  Enter at least the following fields:

* ``Identifier`` is any short name for the container instance.  It does not have to 
  be the same as used in ``lxc launch`` above, and is used only within Wing to
  identify the container.
  
* ``Type`` should be set to ``LXC/LXD``.

* ``Image ID`` is the image name you gave in your ``lxc launch`` call
  (``demo`` in the example above).
  
You may also need to set ``Python Executable`` under the ``Options`` tab of
the container configuration, if there is no executable called ``python`` on
the container. This is needed on Ubuntu 20.04 (the image used in the example
above) because only ``python3`` exists there. If you used that image, select
``Command Line`` and enter ``python3``.

Once you press ``OK`` in the new container configuration dialog, the new container
will be entered into the ``Project Properties`` dialog and you can submit that to
finish project configuration.

Now is a good time to save your project to disk from the new project confirmation
dialog or using ``Save Project`` in the ``Project`` menu.

Testing the Container
---------------------

At this point, Wing should start up the container automatically. The ``Python
Shell`` tool in Wing, available in the ``Tools`` menu, will also restart
using the new configuration, so you can interact with the Python installation
on the container.

The status of the container can be seen in the ``Containers`` tool from the ``Tools`` 
menu.  It can be restarted by right-clicking in the list of containers found there.

Developing Code
---------------

Now you have a working container integration but there is not yet any Python
code that can be run on the container. To add that, use ``New`` in the
``File`` menu, and enter a simple test file as follows:

.. python::

  print('Hello World')
  
Then create a directory on your host system and save the file there as ``test.py``.

Next, add a file mapping to your container configuration by selecting
``Containers`` from the ``Project`` menu, editing the container, and adding
an entry to the ``File Mappings`` list. The ``Host`` entry is the full path
to the directory where your just wrote your ``test.py`` and ``Container`` is
the full path where you want to mount that directory on the container. For
example:

* **Host:**  /home/testuser/demo
* **Container:**  /app

Note that if your container already has a mapping set up in its
configuration, you will need to uncheck ``Establish Mappings`` under the
``File Mappings`` field to prevent Wing from trying to create the mappings
when the container is launched. Then that is unchecked, the mappings listed
here are used only to determine which files on the host match files on the
container. When it is checked, Wing also sets up the mappings for you by
temporarily modifying the container's configuration. For the above simple
demo, this option needs to remain checked.

When you save your container configuration, Wing will restart the container
and your code is now available on the container.

Wing automatically takes care of mapping to and from the container's location
for your source files, and knows that code should be launched on the
container (and not the host system) when debugged or executed because your
``Project Properties`` selected the container for ``Python Executable``.

To debug it, set a breakpoint in your code by clicking in the leftmost margin
in the editor.

Then press the green play icon in the toolbar in Wing or use
``Start/Continue`` in the ``Debug`` menu. You should reach the breakpoint.
Continuing from there causes "Hello World" to appear in Wing's ``Debug
I/O`` tool and the debug process will exit.

That's all there is to it! You can now develop, debug, execute, and test your
Python code in the LXD container environment.

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

For more information see:

* `LXD  <https://linuxcontainers.org/lxd/introduction/>`__ provides more information
  documentation for LXD and LXC.

* `Working with Containers and Clusters <ref: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.


