Skip to content

Update Dockerfile and its README #1098

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Update Dockerfile and its README #1098

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
4b4258b
Update Dockerfile and its README
Bevacizumab Jul 27, 2025
d3ab2da
Switch to Miniforge and update REAME
Bevacizumab Aug 31, 2025
cf0f4f9
Version fix, architecture support, and changes to readme
Bevacizumab Oct 6, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 27 additions & 19 deletions docker/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,8 @@ OpenFermion (or any of its plugins) using the standard procedure.
## What's included?

- Git
- Python 3
- Python 3.12
- [Miniforge](https://github.com/conda-forge/miniforge)
- [OpenFermion](https://github.com/quantumlib/OpenFermion)
- [Cirq](https://github.com/quantumlib/Cirq)
- [Psi4](http://www.psicode.org)
Expand All @@ -26,46 +27,53 @@ OpenFermion (or any of its plugins) using the standard procedure.


## Setting up Docker for the first time
The Dockerfile is based on the [Ubuntu image](https://hub.docker.com/_/ubuntu) (ver. 22.04).
Two Linux architectures are supported in the Dockerfile: x86_64 (amd64) and aarch64 (arm64).
Detecting your host's architecture is handled automatically through the following docker image building process, so you don't have to check it manually.
It creates a Python (ver. 3.12) virtual environment (named `fermion`) using Miniforge and installs all dependencies within it. Psi4 is installed with a [conda command](https://psicode.org/installs/v191/).

You can manually edit the Dockerfile if you need to set up a different development environment (e.g., changing the versions of Ubuntu, Python, Miniforge, Psi4, etc.).

### Building Docker Image
You first need to install [Docker](https://www.docker.com/).
Once Docker is setup, one can navigate to the folder containing the
Dockerfile for building the OpenFermion image (docker/dockerfile) and run
Dockerfile for building the OpenFermion image (/docker/dockerfile) and run

```
docker build -t openfermion_docker .
```

where "openfermion_docker" is just an arbitrary name for our docker image.
Building the Dockerfile starts from a base image of Ubuntu and then installs
OpenFermion, its plugins, and the necessary applications needed for running these
programs. This is a fairly involved setup and will take some time
(perhaps up to thiry minutes depending on the computer). Once installation has
completed, run the image with
(perhaps up to thirty minutes, depending on the computer) and disk space (several gigabytes).

Line 18 in the Dockerfile
```
docker run -it openfermion_docker
COPY . /root/workspace
```
copy the files in the current local directory (where the Dockerfile is located) when the image is built.
If you don't want to copy the files, delete the line first and then build the image.

With this command the terminal enters a new environment which emulates Ubuntu with
OpenFermion and accessories installed. To transfer files from somewhere on the disk to the Docker
container, first run `docker ps` in a separate terminal from the one running
Docker. This returns a list of running containers, e.g.:

### Running the Container
Once the image has been built, run the image with
```
+CONTAINER ID IMAGE COMMAND CREATED
+STATUS PORTS NAMES
+3cc87ed4205b 5a67a4d66d05 "/bin/bash" 2 hours ago
+Up 2 hours competent_feynman
docker run -it --name openfermion_container -v $(pwd):/root/workspace openfermion_docker
```
where "openfermion_container" is an arbitrary choice for the name of our docker container. This command will mount your current local directory, where the Dockerfile is located, to `/root/workspace` inside the running container.
By default, the virtual environment `fermion` is automatically activated in the running container.

In this example, the container name is "competent_feynman" (the name is
random and generated automatically). Using this name, one can then copy
files into the active Docker session from other terminal using:
If you don't want to mount the current directory, run the following command instead:
```
docker run -it --name openfermion_container openfermion_docker
```

### Copy Local Files into the Container
Line 18 in the Dockerfile (`COPY . /root/workspace`) copies the current files only once when the image is built.
Local files in any directories can be copied using:
```
docker cp [path to file on disk] [container name]:[path in container]
```

An alternative way of loading files onto the Docker container is through
remote repos such as GitHub. Git is installed in the Docker image.
After `docker run`, one could run "git clone ..." etc to pull files
Expand Down
86 changes: 41 additions & 45 deletions docker/dockerfile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,48 +12,44 @@

# Dockerfile for OpenFermion, Cirq, and select plugins.

FROM ubuntu

USER root

RUN apt-get update

# Install utilities
RUN apt-get install -y bzip2
RUN apt-get install -y cmake
RUN apt-get install -y git
RUN apt-get install -y wget
RUN apt-get install -y libblas-dev
RUN apt-get install -y liblapack-dev

# Install Python 3
RUN apt-get install -y python3

# Install pip.
RUN apt-get install -y python3-pip

# Install Psi4.
RUN cd /root; wget http://vergil.chemistry.gatech.edu/psicode-download/psi4conda-1.2.1-py36-Linux-x86_64.sh
RUN echo '/root/psi4conda' | bash /root/psi4conda-1.2.1-py36-Linux-x86_64.sh
RUN rm /root/psi4conda-1.2.1-py36-Linux-x86_64.sh
RUN export PATH=/root/psi4conda/bin:$PATH

# Install PySCF.
RUN cd /root; git clone https://github.com/sunqm/pyscf
RUN cd /root/pyscf/pyscf/lib; mkdir build; cd build; cmake ..; make

# Install OpenFermion, Cirq, and plugins.
RUN pip3 install openfermion
RUN pip3 install cirq
RUN pip3 install openfermioncirq
RUN pip3 install openfermionpsi4
RUN pip3 install openfermionpyscf

# Update paths
RUN export PATH=/root/psi4conda/bin:$PATH
RUN export PYTHONPATH=/root/pyscf:$PYTHONPATH

# Make python point to python3
RUN ln -s /usr/bin/python3 /usr/bin/python

ENTRYPOINT bash
FROM ubuntu:22.04

Check warning

Code scanning / Scorecard

Pinned-Dependencies Medium

score is 3: containerImage not pinned by hash
Remediation tip: pin your Docker image by updating ubuntu:22.04 to ubuntu:22.04@sha256:09506232a8004baa32c47d68f1e5c307d648fdd59f5e7eaa42aaf87914100db3
Click Remediation section below for further remediation help

WORKDIR /root/workspace
COPY . /root/workspace

# Set PATH for miniforge
ENV PATH="/root/conda/bin:${PATH}"
# Set PATH for pyscf
ENV PYTHONPATH=/root/pyscf

RUN apt-get update && \
Comment on lines +24 to +25
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For DL3009, I will add a configuration setting to .hadolint.yaml to disable this particular check because it's just not worth the hassle.

For DL3015, go ahead and add the recommended --no-install-recommends flag.

For DL3008, we should probably pin the versions, although there are pros and cons to doing that. One way to find out the versions that can be used is to do roughly the following:

  1. switch to the x86_64 architecture as discuss in a previous comment above
  2. run the docker build as-is
  3. figure out what versions of the packages were installed by the build
  4. edit the file to add those vesions to the apt install command.

I don't know if it's possible with apt-get install, but try to see if it will let you specify just major.minor versions, not full major.minor.patch.whatever; i.e., "12.3" instead of "12.3.0.build34" etc.

apt-get install -y --no-install-recommends bzip2=1.0.8-5build1 \
cmake=3.22.1-1ubuntu1.22.04.2 \
git=1:2.34.1-1ubuntu1.15 \
wget=1.21.2-2ubuntu1.1 \
libblas-dev=3.10.0-2ubuntu1 \
liblapack-dev=3.10.0-2ubuntu1 \
# in order to verify github's certificate
ca-certificates=20240203~22.04.1 \
build-essential=12.9ubuntu3

# Install miniforge https://github.com/conda-forge/miniforge?tab=readme-ov-file#as-part-of-a-ci-pipeline
RUN wget -O Miniforge3.sh "https://github.com/conda-forge/miniforge/releases/download/25.3.1-0/Miniforge3-25.3.1-0-$(uname)-$(uname -m).sh" && \
bash Miniforge3.sh -b -p "${HOME}/conda" && \
conda init bash && \
conda update -n base -c conda-forge conda && \
# Create virtual env (fermion) with installing Psi4
conda create -n fermion psi4 python=3.12 -c conda-forge -y && \
conda install -n fermion pip -y && \
# Install OpenFermion, Cirq, and plugins
conda run -n fermion pip install openfermion \ cirq \ openfermioncirq \ openfermionpsi4 \ openfermionpyscf
Comment on lines +37 to +45

Check warning

Code scanning / Scorecard

Pinned-Dependencies Medium

score is 3: downloadThenRun not pinned by hash
Click Remediation section below to solve this issue

# Install PySCF
WORKDIR /root
RUN git clone https://github.com/sunqm/pyscf
WORKDIR /root/pyscf/pyscf/lib/build
RUN cmake .. && \
make

# Activate venv (fermion)
RUN echo "conda activate fermion" >> ~/.bashrc