Visual Studio Code docker configuration#

These instructions show how to configure Visual Studio Code for SKA control system development using the SKA Docker images. VSCode can be configured to debug using the Python interpreter inside a Docker image, which allows:

  • development and testing without requiring a local Tango installation;

  • the development environment to be identical to the testing and deployment environment, eliminating problems that occur due to differences in execution environment.

Limitations of VSCode docker container debugging compared to PyCharm:

  • Unlike PyCharm Pro Edition, VSCode docker integration doesn’t allow for code completion and linting using a docker container though. Therefore in order to have intellisense (code completion inside VSCode) and linting you will need to have a local installation of the project as well (i.e. a poetry environment).

  • VSCode remote debugging library ptvsd presently conflicts with pytest, meaning that debugging breakpoints cannot be set while running the automated unit testing. Still, you can set any particular unit test file as the entry point for debugging and set breakpoints normally in it. The developing approach should then be to run the unit tests from the terminal, and then in case of errors, to analyze the specific test routine from within the debugger in VSCode.

Improvements to debugging capabilities in VSCode compared to PyCharm:

  • Unlike PyCharm, VSCode does allow for setting up breakpoints on non-asyncio modes.

Follow the steps below to configure VSCode to develop new code and run tests for the ska-tango-examples project using the Docker images for the project.

Prerequisites#

Make sure that the following prerequisites are met:

  • Docker is installed, as described on the page Docker Docs.

  • Visual Studio Code must be installed.

  • You have basic familiarity with VSCode - If this is the first time you have used VSCode, follow the First Steps tutorials so that you know how to use VSCode to develop, debug, and test a simple Python application using a local Python interpreter.

Clone the ska-tango-examples project and get VSCode to recognize it#

  1. Clone the ska-tango-examples repository in your local machine.

  2. Open VSCode from inside the ska-tango-examples folder.

Build the application image (this step is optional)#

With the source code source code checked out, the next step is to build a Docker image for the application. This image will contain the Python environment which will we will later connect to VSCode.

Start a terminal session inside VSCode:

../../../_images/vscode-terminal.png

On the terminal tab build the image by typing make build. This step is optional since the ``make interactive`` command described bellow, takes care of this task if needed:

../../../_images/vscode-build.png

Start the docker container in interactive mode and debug#

Having the built docker image in the system we now start the docker container in interactive mode and are ready to debug.

  • On the terminal tab start the container interactively with make interactive:

../../../_images/vscode-interactive.png

  • Debug a particular file using the vscode-debug.sh utility inside the docker image. For instance ./vscode-debug.sh powersupply/powersupply.py:

../../../_images/vscode-connect.png

Notice that the terminal shell now shows a message stating that it is waiting for the debugger attachment:

tango@b2dbf52b73c7:/app$ ./vscode-debug.sh powersupply/powersupply.py
[+] Waiting for debugger attachment.

  • You can now set breakpoints inside the VSCode editor (or use previously set ones):

../../../_images/vscode-breakpoints.png

  • Start the debugger from whitin VSCode by pressing F5 or the debug button under the debug tab:

../../../_images/vscode-debug.png

Note

For general information on how to use the native VSCode debugger, consult the Debugging documentation from VSCode.

Troubleshooting#

  • make interactive fails

    If the debugger is disconnected improperly, there is a possibility that the docker containers are left running in the background and it isn’t possible to start a new interactive sessions from the VSCode terminal:

    docker run --rm -it -p 3000:3000 --name=powersupply-dev -e TANGO_HOST=databaseds:10000 --network=ska-tango-examples_default \
  -v /home/morgado/Sync/Work/Code/ska/ska-tango-examples:/app registry.gitlab.com/ska-telescope/ska-tango-examples/powersupply:latest /bin/bash
docker: Error response from daemon: Conflict. The container name "/powersupply-dev" is already in use by container "215a9150910605a0670058a0023cbd2d180f1cea11d196b2a413910fb428e290". You have to remove (or rename) that container to be able to reuse that name.
See 'docker run --help'.
Makefile:59: recipe for target 'interactive' failed
make: *** [interactive] Error 125

    In this case you need to check what are the docker containers running using docker ps, and then kill the containers that are running in the background with docker kill CONTAINER_NAME.