2. Development using containers

In order to manage dependencies and versioning inside the project, developing using a containerized environment is recommended.

You can use either Docker or Podman to run the containers, although the tooling for Docker is more mature and better tested.

Start by setting up your local environment as described in the Set up local development environment documentation. This will set up the local environment with the necessary containerization tools and Visual Studio Code.

Note

Most of the instructions in this document assume that you are using Docker, but should work with Podman except for the caveats mentioned on the Docker documentation.

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.

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.

2.1. 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.

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

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

    git clone --recurse-submodules https://gitlab.com/ska-telescope/ska-tango-examples.git

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

    cd ska-tango-examples && code

2.3. Build the application image (this step is optional)

With the 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 oci-build. This step is optional since the ``make interactive`` command described bellow, takes care of this task if needed:

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

2.4. 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 within 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.

2.5. 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.