OpenFOAM Development in VSCode with Docker Containers and Git
“Open-source Field Operation And Manipulation”, OpenFOAM in short, is an objective-oriented C++ toolbox widely used in both academic environments, as well as industrial companies, for the development of customised pre-/post-processing numerical utilities and solvers, in the area of continuum mechanics, and most importantly computational fluid dynamics (CFD).
Starting around 5 years ago, OpenCFD & The OpenFOAM Foundation started to distribute Docker images of their recent releases, along with the traditional repository release.
Dockerized OpenFoam has many advantages, e.g.
- no OF installation required,
- consistent and isolated developing environment,
- easy deployment and ability to run applications on different machines,
- ability to work with different versions on the same machine, etc.
just to name a few.
An IDE, or Integrated Development Environment, allows a smoother interaction between programmers and different aspects of their code.
IDEs increase programmer productivity by merging different tasks of developing software applications, e.g. editing source code in a more interactive UI, creating executables, debugging, version control, etc.
In this regard, Visual Studio Code (VSCode) offers a free and lightening-fast source code editor with functionalities of a professional integrated development environment. It offers valuable features like syntax highlighting, bracket-matching, auto-indentation, box-selection, version control gadgets, IntelliSense code completion, rich semantic code understanding and navigation, code refactoring, snippets, and more.
For serious coding, Specially in the case of prominent scientific codes like OpenFOAM, you’ll often benefit from tools with more code understanding than just blocks of text in a terminal Vim.
To start with remote OpenFOAM development in containerised environment with VSCode, needless to say, the latest version of VSCode and Docker need to be installed on the Host Machine.
To get started, you need to install the “Docker” Extension of VSCode from “Market Place” as well:
Once installed, you would be able to see a list of the images and containers on your local host in the Docker extension menu, where you would be able to run any container with a simple click:
If you wish to provide more arguments for the run commands of any Image, you can always access the terminal right inside the VSCode:
Now it’s time to create the Dockerfile based on the specifications that you wish to use for Docker Container of OpenFOAM. Here is the version of Dockerfile that I created/use:
- Line 1: specifies the Base Images that you wish to use for your Image. I develop based on the official Image of latest version of OpenFOAM-v2006
- Line 3: installs the applications that you wish to have in the Centos-OS of the image using the command `RUN yum …`
- Line 4: specifies the user of OpenFOAM. In this case I specify the `ofuser` as the user in the OF bashrc file
- Line 6: specifies the terminal bash
- As the source-codes in OF are specified with the file-type extensions of *.C, the intellisense engine fails to comprehend the structure of the code and many useful functionalities of VSCode will be disabled, e.g. code completion, Go to Defenition/Declaration, Inheritance Hieratchy, etc. The tools that could be very useful specially for understanding the source code. To solve this issue, in line 10, I copy a file settings.json into .vscode directory of the OF source code. The content of this file is:
- Line 12: specifies the name of the container user account. Remember that you can run the container with root access if you replace the ofuser with root. But running MPI applications in root is not encouraged.
- Usually I copy the .bashrc and .vimrc files of my local host (Possible for Mac/Linux distributions) to have the same vim and bash experience as I have in my host. Lines 15–16 do this.
- Needless to say that for OF applications, two files of OF bashrc and OF setImage_v2006.sh need to be sourced. That is why I add the following two lines to my .bashrc file
source /opt/OpenFOAM/OpenFOAM-v2006/etc/bashrc WM_NCOMPPROCS=4 WM_MPLIB=SYSTEMOPENMPI FOAM_CONFIG_NOUSER=unsetsource /opt/OpenFOAM/setImage_v2006.sh
- Line 18: creates .ssh directory to hold future ssh-keys from the host, required for git version control
- The last line 19 creates the directory of $USER_RUN that is usually used to track the OF case files.
Once you have the Dockerfile ready, you can right-click on it in the EXPLORER menu and select “Build Image …” and specify a name:tag for your Image:
If you don’t receive any errors along the way, you will see the following lines in your VSCode terminal output with name:tag of your image:
And you will be able to see the built image in your Images:
It is possible to right-click on the Image, and select “Run” or “Run Interactive”, but since we wish for mounting volumes to the docker container, better to do this task in the terminal of VSCode via:
localHost-> docker run --rm -it -v ~/.ssh:/root/.ssh -v $PWD/ofuser:/OpenFOAM/ofuser-v2006 vscodedockerof:latest bash
This command basically runs the docker image that you just created (yourImageName:yourTag).
- “— rm” eliminates the container once it is closed,
- “-it” runs the container in interactive mode through a terminal
- “-v” mounts a volume from local host to the container: “~/.ssh:/ofuser/.ssh”, mounts the volume “~/.ssh” to “/ofuser/.ssh”, thus the public key copied into your git key registry would be unlocked with the private key copied in “/ofuser/.ssh”, allowing easier git integration in your container. $PWD/ofuser:/OpenFOAM/ofuser-v2006 mounts the volume ofuser in your working directory of your host into ofuser-v2006 working directory of your OF container, thus all your simulations (in run directory) or your modified source codes (in src directory) will be saved in the local machine once you exit the container.
once you run the above command, you would enter the docker container of created image and will see, where you have all the functionalities of OpenFOAM:
You can attach VSCode to the running container through the right-click on running container and selecting “Attach Visual Studio Code”:
This would open a visual studio code IDE in the container where you can use all the functionalities of VSCode for OpenFOAM:
including git-integration with a more user friendly GUI, where viewing/controlling changes, stages, commits, remote repositories, branches, etc. was never easier:
Any other functionalities required could be reached trough the command palette by Ctrl+Shift+P (⌘+shift+P for Mac):