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
+72 −65
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
b328da4
Update Dockerfile and its README
Bevacizumab Jul 27, 2025
f71d433
Switch to Miniforge and update REAME
Bevacizumab Aug 31, 2025
0c589ec
Merge branch 'master' into update_docker_readme
mhucka Sep 25, 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
55 changes: 32 additions & 23 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 @@ -27,9 +28,28 @@ 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).
It creates a Python (ver. 3.12) virtual environemnt (named `fermion`) using Miniforge and installs all dependencies within it. Psi4 is installed with a conda [command](https://psicode.org/installs/v191/).
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
It creates a Python (ver. 3.12) virtual environemnt (named `fermion`) using Miniforge and installs all dependencies within it. Psi4 is installed with a conda [command](https://psicode.org/installs/v191/).
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/).

The default configuration uses the latest Miniforge installer on Linux `aarch64` architecture.
Copy link
Contributor

Choose a reason for hiding this comment

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

Why does this change the default from the previous x86_64 architecture? From our experiences, x86_84-based systems are still more common than arm64 systems.


### Customizing the Environment
You can manually edit the Dockerfile if you need to set up a different development environment (e.g., changing the Ubuntu, Python, Miniforge, or Psi4 version).

If your local machine builds Linux `x86_64` architecture with the Dockerfile, the `wget` command
for the Miniforge installer (Line 40 in the Dockerfile)
```
wget -O Miniforge3.sh "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-aarch64.sh"
```
must be changed to
```
wget -O Miniforge3.sh "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-x86_64.sh"
```
You can check other Miniforge installers [here](https://github.com/conda-forge/miniforge?tab=readme-ov-file#requirements-and-installers).

### 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 .
Expand All @@ -39,32 +59,21 @@ 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).

### Running the Container
Once the image has been built, run the image with
```
docker run -it openfermion_docker
docker run -it --name openfermion_container -v $(pwd):/root/workspace openfermion_docker
```

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

```
+CONTAINER ID IMAGE COMMAND CREATED
+STATUS PORTS NAMES
+3cc87ed4205b 5a67a4d66d05 "/bin/bash" 2 hours ago
+Up 2 hours competent_feynman
```

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:

where "openfermion_container" is an arbitrary choice for the name of our docker container. This command will mount your current local directory to `/root/workspace` inside the running container.
By default, the virtual environment `fermion` is automatically activated in the running container.
After installing the `Dev Containers` extension in Visual Studio Code,
you can open the container with the following option:
```
docker cp [path to file on disk] [container name]:[path in container]
Command Palette -> Dev Containers: Attach to Running Container..
Copy link
Contributor

Choose a reason for hiding this comment

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

This change refers to a GUI interface, correct? As far as I know, docker does not provide a GUI. There is a separate tool, Docker Desktop, that provides a GUI, but we can't assume that users will be using that. (Also, Docker Desktop has license restrictions.)

Please revert this back to CLI-based instructions.

```
and select `openfermion_container` for this example.

An alternative way of loading files onto the Docker container is through
remote repos such as GitHub. Git is installed in the Docker image.
Expand Down
82 changes: 40 additions & 42 deletions docker/dockerfile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,48 +12,46 @@

# Dockerfile for OpenFermion, Cirq, and select plugins.

FROM ubuntu
FROM ubuntu:22.04

USER root

Check failure on line 17 in docker/dockerfile

View workflow job for this annotation

GitHub Actions / Dockerfile lint checks 

DL3002 warning: Last USER should not be root
Copy link
Contributor

Choose a reason for hiding this comment

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

This was in the original Dockerfile, and not a new addition, but it may as well be fixed as part of this PR. The Dockerfile should not need root, so it should be possible to omit this line entirely. (I'm not sure why the original had it in the first place.) Removing the line will solve the check failure about "USER should not be 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
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 && \

Check failure on line 27 in docker/dockerfile

View workflow job for this annotation

GitHub Actions / Dockerfile lint checks 

DL3009 info: Delete the apt lists (/var/lib/apt/lists) after installing something

Check failure on line 27 in docker/dockerfile

View workflow job for this annotation

GitHub Actions / Dockerfile lint checks 

DL3015 info: Avoid additional packages by specifying `--no-install-recommends`

Check failure on line 27 in docker/dockerfile

View workflow job for this annotation

GitHub Actions / Dockerfile lint checks 

DL3008 warning: Pin versions in apt get install. Instead of `apt-get install <package>` use `apt-get install <package>=<version>`
Comment on lines +26 to +27
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 build-essential \
bzip2 \
cmake \
git \
wget \
libblas-dev \
liblapack-dev \
curl

# 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/latest/download/Miniforge3-Linux-aarch64.sh" && \

Check failure on line 38 in docker/dockerfile

View workflow job for this annotation

GitHub Actions / Dockerfile lint checks 

DL3003 warning: Use WORKDIR to switch to a directory
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 && \
# Install PySCF
cd /root && \
git clone https://github.com/sunqm/pyscf && \
cd /root/pyscf/pyscf/lib && \
mkdir build && \
cd build && \
cmake .. && \
make

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