Running QMCPACK on Docker Containers
This guide will briefly cover running QMCPACK on your machine using a docker container. Docker containers are a portable way to achieve reproducibility across all developers and users. Two main uses:
Debugging CI related issues running on Docker containers that are not reproducible in other environments.
Ease the learning curve by providing a ready-to-go environment in a single container (binary available in DockerHub) to new community members.
Docker containers are identified by domain/image:tag and stored using The Github Container Registry. Currently available containers have pre-installed QMCPACK dependencies, see the Dockerfile file link for available dependencies on each image:
Running Docker Containers
After installation run the following command to verify the Docker engine is properly installed. Note: restart your system if necessary.
docker run hello-world
Pull an image (optional, see 3): once Docker is properly installed and running on your system, use the following command to download a QMCPACK image and tag:
docker pull ghcr.io/qmcpack/ubuntu22-openmpi:latest
Run an image: the docker run command will spin up a container with using the image we just downloaded from step 2. Alternatively, docker run will automatically fallback to pulling the image and tag from DockerHub (requires connection).
For a quick and safe, non sudo, run:
docker run -it ghcr.io/qmcpack/ubuntu22-openmpi:latest /bin/bash
The above will run the container in interactive mode dropping the default user to /home/user using the bash shell. If sudo access is needed (e.g. install a package sudo apt-get install emacs) the password for the default user is also user.
Run an image (for Development) docker run has a few extra options that can be used to run QMCPACK:
docker run -u $(id -u `stat -c "%U" .`):$(id -g `stat -c "%G" .`) -v <QMCPACK Source Directory>:/home/user -it ghcr.io/qmcpack/ubuntu22-openmpi:latest /bin/bash
Flags used by docker run (Note: The flags -i and -t are combined above):
-u : For building we need write permissions, the current arguments will set your container user and group to match your host user and group (e.g. install additional packages, allocating shared volume permissions, etc.).
-v : Replace <QMCPACK Source Directory> with the direct path to your QMCPACK directory, this maps it to our landing directory and gives docker access to the files
-i : Specifies the image to use
-t : Allocate a pseudo-tty, allows an instance of bash to pass commands to it
As an example, if extra permissions are needed the container can be run with the sudo user (not recommended):
docker run -u root -v path/to/QMCPACK:home/user -it ghcr.io/qmcpack/ubuntu22-openmpi:latest /bin/bash
Build QMCPACK on Docker
The following steps just follow a regular QMCPACK build on any Linux environment
Get QMCPACK: use https as ssh requires extra authentication
Option 1 (fresh build):
git clone https://github.com/QMCPACK/qmcpack.git cd build
Option 2 (for development):
Note: this assumes you have mapped your QMCPACK directory as outlined above, else traverse to your source directory, then the build folder inside.
cmake -GNinja \ -DCMAKE_BUILD_TYPE=RelWithDebInfo \ -DCMAKE_C_COMPILER=mpicc -DCMAKE_CXX_COMPILER=mpicxx \ -DQMC_COMPLEX=0 \ ..
Note: To reproduce the build in the Docker container used by GitHub Actions CI pipeline we provide an optimized build with debug symbols -DCMAKE_BUILD_TYPE=RelWithDebInfo , but users can select any other cmake build type(Release being default):
ctest -VV -R deterministic-unit_test_wavefunction_trialwf ctest -L deterministic
OpenMPI strongly advises against running as a root user, see docs