Docker Workflow

This section collects all container-based workflows for Phlegethon.

Install Docker

macOS

Install Docker Desktop:

  • https://docs.docker.com/desktop/setup/install/

Or via Homebrew:

brew install --cask docker

After installation, start Docker Desktop and confirm:

docker --version
docker compose version

Ubuntu or Debian

Use Docker Engine and Docker Compose plugin:

  • https://docs.docker.com/engine/install/ubuntu/

  • https://docs.docker.com/compose/install/linux/

Quick install (distribution packages):

sudo apt update
sudo apt install -y docker.io docker-compose-v2
sudo usermod -aG docker "$USER"

Log out and back in, then verify:

docker --version
docker compose version

Fedora

Use Docker Engine and Compose plugin:

  • https://docs.docker.com/engine/install/fedora/

Quick install:

sudo dnf install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo systemctl enable --now docker
sudo usermod -aG docker "$USER"

Log out and back in, then verify:

docker --version
docker compose version

Build and Run (Dockerfile)

Build an Ubuntu-based image (default):

docker buildx build --load -t phlegethon:ubuntu .

If buildx is not available yet, use:

docker build -t phlegethon:ubuntu .

Compile a test case in the container:

docker run --rm -it -v "$PWD":/opt/phlegethon -w /opt/phlegethon phlegethon:ubuntu bash -lc 'cd tests/hotbubble && make clean && make'

Run with default container command:

docker run --rm -it -v "$PWD":/opt/phlegethon -w /opt/phlegethon -e TEST_CASE=tests/hotbubble -e MPI_RANKS=4 phlegethon:ubuntu

Build and Run (Docker Compose)

Build image with compose:

docker compose build

Compile a test case:

docker compose run --rm phlegethon bash -lc 'cd tests/hotbubble && make clean && make'

Run with compose defaults (TEST_CASE=tests/hotbubble, MPI_RANKS=4):

docker compose run --rm phlegethon

Override runtime options:

TEST_CASE=tests/hotbubble-helmholtz MPI_RANKS=2 docker compose run --rm phlegethon

Use a different base image (example Fedora):

BASE_IMAGE=fedora:41 \
INSTALL_CMD='dnf install -y gcc gcc-c++ gcc-gfortran make pkgconf-pkg-config openmpi openmpi-devel hdf5-openmpi hdf5-openmpi-devel python3 python3-pip python3-devel ninja-build && dnf clean all' \
docker compose build --no-cache

Python Post-Processing in Containers

The image includes a dedicated Python virtual environment at /opt/phl_env with:

  • numpy

  • matplotlib

  • scipy

  • h5py

  • ipython

  • jupyterlab

  • meson

  • ninja

The Fortran module eos_fort is compiled during image build from miscellaneous/eos/eos.f90 and installed into this environment.

Validate post-processing environment:

docker compose run --rm phlegethon python -c 'import h5py, numpy, matplotlib; print("post-processing env OK")'
docker compose run --rm phlegethon python -c 'import eos_fort; print(eos_fort.__file__)'

Interactive Python:

docker compose run --rm phlegethon ipython

Customize Python packages at build time:

PYTHON_PACKAGES='numpy matplotlib scipy h5py ipython jupyterlab meson ninja pandas' docker compose build --no-cache

JupyterLab

Start JupyterLab:

docker compose up phlegethon-jupyter

Open:

  • http://localhost:8888

Jupyter runs without a token for local development in this setup.

Stop Jupyter service:

docker compose stop phlegethon-jupyter

Matplotlib in notebooks:

%matplotlib inline
import matplotlib.pyplot as plt

Access Output Files

  • With docker run, include -v "$PWD":/opt/phlegethon -w /opt/phlegethon so outputs are written to host files.

  • With compose, outputs are persisted via the ./:/opt/phlegethon bind mount.

Inspect outputs from host:

ls -lh tests/hotbubble-helmholtz
tail -n 100 tests/hotbubble-helmholtz/restart_info.txt

Interactive Container Access and Logs

Open an interactive shell (docker run):

docker run --rm -it -v "$PWD":/opt/phlegethon -w /opt/phlegethon --entrypoint bash phlegethon:ubuntu

Open an interactive shell (compose):

docker compose run --rm phlegethon bash

Typical interactive session:

cd tests/hotbubble-helmholtz
make clean
make
mpirun -n 4 ./run.app
tail -n 100 restart_info.txt

Detached run with log monitoring:

docker compose run -d --name phl-run phlegethon
docker logs -f phl-run
docker exec -it phl-run bash
docker rm -f phl-run

Troubleshooting

  • docker build requires 1 argument: you missed the build context. Keep trailing ..

  • legacy builder is deprecated: install or enable buildx, then use docker buildx build --load ....