Devcontainers: Developing HYDROLIB in an isolated environment¶
A common struggle while working on any software project, is to ensure all of your dependencies are available and you can actually build the software, run the tests etc. While any developer is free to choose their own toolchain, environment etc, HYDROLIB-Core includes the necessary files to run the project within a so called devcontainer within Visual Studio Code. With the help of Docker, we can spin up an independent development environment, ensuring that HYDROLIB-Core works out of the box and you are insulated from any specific local configurations on your machines. This should allow you to start working on HYDROLIB-Core quickly.
The following sub sections will walk you through the necessary dependencies, and how to use it, and modify it, to fit your own needs. This will be done in the following order:
- Requirements: Docker and Visual Studio Code Remote - Containers extension
- Dockerfile configures python, poetry and other dependencies
- devcontainer.json specifies how visual studio code should be configured
- External references
Requirements: Docker and Visual Studio Code Remote - Containers extension¶
In order to run HYDROLIB in a dev container we need the following dependencies
Docker will ensure we can spin up an isolated container. A full tutorial on how to use Docker is outside the scope of this tutorial, however the Getting Started guide of Docker should provide you with the steps to install Docker on your machine.
Visual Studio Code is the editor we will use. The website should provide you with the necessary steps to install it.
Lastly, we need to install the Visual Studio Code Remote - Containers extension. The install button on the marketplace should walk you through the steps to install it.
Run HYDROLIB in a devcontainer by executing "Reopen in container" command¶
With all of the dependencies set up, we should be able to run HYDROLIB within our devcontainer. When opening the HYDROLIB-Core repository in Visual Studio Code, we should either get a pop-up asking us to reopen the project within a remote container, or we can select the "Open a Remote Window" button, the green button in the bottom left corner of your visual studio code window, after which we can select "Reopen in container". Both will then spin up a new container in which we can work. Note that if it is the first time starting our repository, or if we have made changes to the Docker Images we might need to build the container, which could take a few moments.
Once opened in a separate container, we can start a terminal to verify everything is working correctly. When we start a new terminal, we should see the terminal of our container, e.g. something a long the lines of
(.venv) root@7573572275f1:/workspaces/HYDROLIB-core#
It should now be possible to run the HYDROLIB-Core tests within our container. You might get prompted to configure either the python interpreter, or the python test framework. Once this is done all tests should pass as they would normally.
Dockerfile configures python, poetry and other dependencies¶
The Dockerfile which specifies our specific devcontainer can be found here in the repository. Currently, it extends the python 3.9 buster image provided by the Python foundation. It then does the following:
- Installs Poetry 1.1.11 and configure the necessary paths
- Copies the poetry.lock and pyproject.toml and installs the project
- Installs git within the container
This should provide us with a ready to go environment to run HYDROLIB-Core with.
devcontainer.json specifies how visual studio code should be configured¶
We can further customise our environment by editing the devcontainer.json located here in the repository. In particular, you can add any Visual Studio Code extensions you require for your work to the extensions field. Currently it is populated with several common Python extensions which we use to develop HYDROLIB.
For a full overview how to customise this file, you can find the documentation here