Creating a New Docker Container with Wing Pro
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.
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.
