MFC Containerization #971
MFC Containerization #971
Conversation
PR Reviewer Guide 🔍Here are some key observations to aid the review process:
|
PR Code Suggestions ✨Explore these optional code suggestions:
|
|||||||||||||
|
https://hub.docker.com/r/mohdsaid497566/mfc/tags?ordering=name |
|
Running shb-m1pro-3: spencer/Downloads $ docker run --rm -it --platform=linux/amd64 mohdsaid497566/mfc:v4.9.6-cpu
root@6175637cf718:/opt/MFC# ls
CITATION.cff Dockerfile README.md build examples mfc.sh src toolchain
CMakeLists.txt LICENSE benchmarks docs mfc.bat misc tests
root@6175637cf718:/opt/MFC# ./mfc.sh run ./examples/1D_sodshocktube/case.py -n 1 -j 20
mfc: OK > (venv) Entered the Python 3.10.12 virtual environment (>= 3.8).
.=++*: -+*+=. | root@6175637cf718 [Linux]
:+ -*- == =* . | -------------------------
:*+ == ++ .+- |
:*##-.....:*+ .#%+++=--+=:::. | --jobs 20
-=-++-======#=--**+++==+*++=::-:. | --mpi --no-gpu --no-debug --no-gcov --no-unified
.:++=----------====+*= ==..:%..... | --targets pre_process, simulation, and post_process
.:-=++++===--==+=-+= +. := |
+#=::::::::=%=. -+: =+ *: | ----------------------------------------------------------
.*=-=*=.. :=+*+: -...-- | $ ./mfc.sh (build, run, test, clean, count, packer) --help
Acquiring /opt/MFC/examples/1D_sodshocktube/case.py...
Acquiring /opt/MFC/examples/1D_sodshocktube/case.py...
Build | syscheck, syscheck, pre_process, simulation, and post_process | Generic Build
Generating case.fpp.
Writing a (new) custom case.fpp file.
$ cmake --build /opt/MFC/build/staging/7d9b728a37 --target syscheck --parallel 20 --config Release
[100%] Built target syscheck
$ cmake --install /opt/MFC/build/staging/7d9b728a37
-- Install configuration: "Release"
-- Up-to-date: /opt/MFC/build/install/7d9b728a37/bin/syscheck
Generating case.fpp.
Writing a (new) custom case.fpp file.
$ cmake --build /opt/MFC/build/staging/9a4af0a3bd --target pre_process --parallel 20 --config Release
[100%] Built target pre_process
$ cmake --install /opt/MFC/build/staging/9a4af0a3bd
-- Install configuration: "Release"
-- Up-to-date: /opt/MFC/build/install/9a4af0a3bd/bin/pre_process
Generating case.fpp.
Writing a (new) custom case.fpp file.
$ cmake --build /opt/MFC/build/staging/98998883b5 --target simulation --parallel 20 --config Release
[100%] Built target simulation
$ cmake --install /opt/MFC/build/staging/98998883b5
-- Install configuration: "Release"
-- Up-to-date: /opt/MFC/build/install/98998883b5/bin/simulation
Generating case.fpp.
Writing a (new) custom case.fpp file.
$ cmake --build /opt/MFC/build/staging/03b34a2688 --target post_process --parallel 20 --config Release
[100%] Built target post_process
$ cmake --install /opt/MFC/build/staging/03b34a2688
-- Install configuration: "Release"
-- Up-to-date: /opt/MFC/build/install/03b34a2688/bin/post_process
Run
Using queue system Interactive.
Using baked-in template for default.
Generating input files for syscheck...
Generating syscheck.inp:
INFO: Forwarded 0/49 parameters.
Generating input files for pre_process...
Generating pre_process.inp:
INFO: Forwarded 31/49 parameters.
Generating input files for simulation...
Generating simulation.inp:
INFO: Forwarded 33/49 parameters.
Generating input files for post_process...
Generating post_process.inp:
INFO: Forwarded 20/49 parameters.
$ /bin/bash /opt/MFC/examples/1D_sodshocktube/MFC.sh
+-----------------------------------------------------------------------------------------------------------+
| MFC case # MFC @ /opt/MFC/examples/1D_sodshocktube/case.py: |
+-----------------------------------------------------------------------------------------------------------+
| * Start-time 00:47:07 * Start-date 00:47:07 |
| * Partition N/A * Walltime 01:00:00 |
| * Account N/A * Nodes 1 |
| * Job Name MFC * Engine interactive |
| * QoS N/A * Binary N/A |
| * Queue System Interactive * Email N/A |
+-----------------------------------------------------------------------------------------------------------+
mfc: WARNING > This is the default template.
mfc: WARNING > It is not intended to support all systems and execution engines.
mfc: WARNING > Consider using a different template via the --computer option if you encounter problems.
mfc: OK > :) Selected MPI launcher mpirun. Use --binary to override.
mfc: OK > :) Running syscheck:
+ mpirun -np 1 /opt/MFC/build/install/7d9b728a37/bin/syscheck
[TEST] MPI: call mpi_init(ierr)
[TEST] MPI: call mpi_comm_rank(MPI_COMM_WORLD, rank, ierr)
[TEST] MPI: call mpi_barrier(MPI_COMM_WORLD, ierr)
[TEST] MPI: call assert(rank >= 0)
[TEST] MPI: call mpi_comm_size(MPI_COMM_WORLD, nRanks, ierr)
[TEST] MPI: call assert(nRanks > 0 .and. rank < nRanks)
[SKIP] ACC: devtype = acc_get_device_type()
[SKIP] ACC: num_devices = acc_get_num_devices(devtype)
[SKIP] ACC: call assert(num_devices > 0)
[SKIP] ACC: call acc_set_device_num(mod(rank, nRanks), devtype)
[SKIP] ACC: allocate(arr(1:N))
[SKIP] ACC: !$acc enter data create(arr(1:N))
[SKIP] ACC: !$acc parallel loop
[SKIP] ACC: !$acc update host(arr(1:N))
[SKIP] ACC: !$acc exit data delete(arr)
[TEST] MPI: call mpi_barrier(MPI_COMM_WORLD, ierr)
[TEST] MPI: call mpi_finalize(ierr)
Syscheck: PASSED.
mfc: OK > :) Running pre_process:
+ mpirun -np 1 /opt/MFC/build/install/9a4af0a3bd/bin/pre_process
Program received signal SIGILL: Illegal instruction.
Backtrace for this error:
#0 0x7fffff49e960 in ???
#1 0x7fffff49dac5 in ???
#2 0x7fffff09051f in ???
#3 0x55555555cfd3 in MAIN__
#4 0x5555555575fe in main
--------------------------------------------------------------------------
Primary job terminated normally, but 1 process returned
a non-zero exit code. Per user-direction, the job has been aborted.
--------------------------------------------------------------------------
--------------------------------------------------------------------------
mpirun noticed that process rank 0 with PID 0 on node 6175637cf718 exited on signal 4 (Illegal instruction).
--------------------------------------------------------------------------
mfc: ERROR > :( /opt/MFC/build/install/9a4af0a3bd/bin/pre_process failed with exit code 132. |
|
Also I no longer see codespaces available in the MFC repo |
|
for setting up a codespace in the MFC repo (under mflowcode) i have this in my settings: Codespaces |
|
as someone unfamiliar with docker but familiar with many other "coding thing" I was unable to get this running after trying many different things |
This sounds like the right path, I just can't run the containers on my machine right now (so new users definitely won't use it in current state. if macos + arm is the issue, well many people own Macbooks...) |
Yeah I just tried that specific image and I do not seem to have any issues running anything on wsl or codespaces. I will see if I can maybe downgrade ubuntu or get a functional base container for macos to make it run somehow.
If you want try it on Phoenix till I figure something out - or anything non-macos. |
|
https://docs.docker.com/build/building/multi-platform/ Found this doc on multi-platform builds that Docker automatically selects the correct variant based on the host's architecture |
Well you could deploy an ARM compatible container. That's one option. But I've run docker with x86 code in it without issue on my Mac before (just had to add a flag so it knew what to do). I tried this with your container but it didn't work. Also I'm still confused about codespaces. Did you just enable it on your fork or something?
Yeah I "tried" that but Phoenix doesn't have docker or singularity/apptainer? I must be missing something here. |
So presumably this builds both versions, I suppose? We could try it out. I feel like this might be the equivalent of me using |
No, on the base and fork, I do not seem to be having any issues starting a codespace at all.
The cli's do not exist in the login node. If you start an interactive job, you should be able to use apptainer and singularity directly there.
Whether multi-platform or arch-specific containers, I will experiment and compare whichever is better. |
Can you post a screenshot(s)? I don't see it anymore (I used to see it... which is why i suggested it)
Sounds good to me. NVHPC should support but you may have to be careful what image of theirs you pull down. |
Oh interesting. I don't see them when doing this on Phoenix nor Bridges2. What computer showed you this, did you have to load other modules first? |
Without loading any module, I just tried phoenix, bridges2, and delta with on-demand and ssh, and I was able to use them. |
Indeed... apptainer works from compute nodes. |
|
this is still draft (not ready for review). it needs a user guide and a way for users to deploy in both user cases: 1. the programmer on a computer w/o internet and 2. the newcomer that knows very very little. In each case I think we have some improvements to make to clarify what to do and how to do it. the newcomer may benefit from codespaces but i just tried it myself and couldn't figure out what to do from the vscode codespace. that said, i was able to pull the docker container onto my mac when looking at your dockerhub for arm64 and that did indeed work |
|
BTW look at that old MFC logo! very cool |
|
PS let me know when this is ready for me to look at again |
|
Status Update: Pre-configured Repo Codespaces https://github.com/Malmahrouqi3/MFC-mo2/ Docker GUI can be used to run any containerized release. It would prior stop instantly after startup unless there was an active running command pre-written. However, currently, it starts and stops when instructed by user via GUI buttons. It is pretty cool right now that you can retrieve any release and play with it within seconds under Exec tab. |
very well done @Malmahrouqi3! This is really a blast from the past... I can't even remember the ordering of commands to get it to run with tip: we'll want to keep this requiring minimal upkeep, so it just keeps rolling out containers but otherwise doesn't need to be updated. right now it looks like you have a separate readme for the dockerhub, which closely mirrors the current MFC readme with some changes. this isn't really maintainable... MFC readmes change rapidly as I occasionally kill time messing with it. A minimal but everlasting readme is better (even if it's less attractive to look at). |
There was a problem hiding this comment.
Pull Request Overview
This PR introduces Docker containerization support for MFC, enabling both CPU and GPU container variants with automated builds and deployment. The implementation provides a comprehensive containerization solution that allows users to run MFC in standardized environments across different platforms.
Key Changes:
- Docker containerization with CPU/GPU variants using appropriate base images and compilers
- Automated GitHub Actions workflow for building and deploying containers on releases
- Multi-architecture support with manifest creation for cross-platform compatibility
Reviewed Changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| .github/workflows/docker.yml | GitHub Actions workflow for automated container builds and Docker Hub deployment |
| .github/Dockerfile | Multi-stage Dockerfile supporting both CPU (Ubuntu) and GPU (NVIDIA HPC SDK) variants |
| .github/.dockerignore | Docker ignore patterns to exclude build artifacts and temporary files from container builds |
| .devcontainer/devcontainer.json | GitHub Codespaces configuration to automatically load MFC container environment |
PR Code Suggestions ✨Explore these optional code suggestions:
|
||||||||||||||
I'm not quite sure what this means, are you asking someone else to do something, or waiting for some automated process to finish? |
My bad. Since I do not have access to your docker credentials, can you please do it so they all be posted in under |
|
Or to make it simpler can you add me as a collaborator in the docker repo |
It seems like we should make a username |
|
I guess you can make some sort of org in docker instead of personal account. |
1 similar comment
|
I guess you can make some sort of org in docker instead of personal account. |
|
@Malmahrouqi3 I gave you collaborator access so you can finish it off! |
|
I have been pushing stuff but it is taking some time |
|
Oh wow. We don't have to go forever back, but doing by release for some sensible amount of time makes sense. What is the limit to how far back we can go in terms of (a) logistics [things like breaking changes to the ./mfc.sh command] and (b) size of dockerhub space? also, does this autopopulate new tags/releases? |
As far as I am concerned no storage limitation for docker images sorta similar to GitHub. The workflow file |
|
status? it's unclear to me if this is 'working', to what degree it has been tested, how it works, how i should test it, etc.? |
|
Question concerning having to run in |
|
add to getting started docs Using ContainersAs an alternative to building MFC from scratch, use containers via either Docker Desktop or Docker CLI.
docker run -it --rm sbryngelson/mfc:latest-cpu
Navigating Docker Desktop:
Please refer to the docker repository readme for more details on how to properly use containers. |
|
for this part
can we just put the docker repository readme in the main docs as a separate tab under documentation? that way it's all in one place. in the docker repo you can put Also we should include documentation on how people can use dev containers from the root repo under clone. That isn't obvious to people that it even exists. they should also be documentation on which container to pick based on what computer you're using. |
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
This PR is being reviewed by Cursor Bugbot
Details
You are on the Bugbot Free tier. On this plan, Bugbot will review limited PRs each billing cycle.
To receive Bugbot reviews on all of your PRs, visit the Cursor dashboard to activate Pro and start your 14-day free trial.
.github/workflows/docker.yml
Outdated
| CXX_COMPILER=${{ contains(matrix.config.name, 'gpu') && 'nvc++' || 'g++' }} | ||
| FC_COMPILER=${{ contains(matrix.config.name, 'gpu') && 'nvfortran' || 'gfortran' }} | ||
| COMPILER_PATH=${{ contains(matrix.config.name, 'gpu') && '/opt/nvidia/hpc_sdk/Linux_x86_64/compilers/bin' || '/usr/bin' }} | ||
| COMPILER_LD_LIBRARY_PATH=${{ contains(matrix.config.name, 'gpu') && '/opt/nvidia/hpc_sdk/Linux_x86_64/compilers/lib' || '/usr/lib' }} |
There was a problem hiding this comment.
Bug: GPU Build Paths Incorrect for ARM
The COMPILER_PATH and COMPILER_LD_LIBRARY_PATH for GPU builds are hardcoded to Linux_x86_64 in the NVIDIA HPC SDK path. This causes builds on ARM runners (like ubuntu-22.04-arm) to fail, as the correct path for ARM is Linux_aarch64.
| ENV OMPI_ALLOW_RUN_AS_ROOT_CONFIRM=1 | ||
| ENV PATH="/opt/MFC:$PATH" | ||
|
|
||
| COPY ../ /opt/MFC |
There was a problem hiding this comment.
Bug: Build Context Restricts Parent Directory Access
The COPY ../ instruction tries to access the parent directory of the build context. Since the build context is /mnt/share, ../ resolves to /mnt, preventing the repository files at /mnt/share from being copied into the image. This results in missing or incorrect files.
| docker manifest create $REGISTRY:$TAG-cpu $REGISTRY:$TAG-cpu-ubuntu-22.04 $REGISTRY:$TAG-cpu-ubuntu-22.04-arm | ||
| docker manifest create $REGISTRY:$TAG-gpu $REGISTRY:$TAG-gpu-ubuntu-22.04 $REGISTRY:$TAG-gpu-ubuntu-22.04-arm | ||
| docker manifest create $REGISTRY:latest-cpu $REGISTRY:$TAG-cpu-ubuntu-22.04 $REGISTRY:$TAG-cpu-ubuntu-22.04-arm | ||
| docker manifest create $REGISTRY:latest-gpu $REGISTRY:$TAG-gpu-ubuntu-22.04 $REGISTRY:$TAG-gpu-ubuntu-22.04-arm |
There was a problem hiding this comment.
Bug: Manifest Tags Overwritten, Causing Race Conditions
The latest-cpu and latest-gpu manifest tags are unconditionally overwritten by each workflow run. This means latest might point to an older or incorrect version, especially with concurrent runs or out-of-order processing, creating a race condition for the latest reference.
|
Status Update: Further, running locally Memory binding failure rarely occurs because of inherent MPI Limitation leading to few MFC tests failure and negative runtimes - reference mpi-limitation-for-docker. If encountered, simply increase the shared memory size 7A9F4EF4 1.82 2D -> Example -> axisym_shockbubble
F05E1CEF 1.60 0D -> Example -> bubblecollapse_adap
2BA0324F 2.29 2D -> Example -> rayleigh_taylor
Failed test tests/5B195322: 3D -> Example -> lagrange_shbubcollapse after 1 attempt(s).
D827EA4B 9.96 3D -> Example -> acoustic_support11
7BCDC8E7 -0.65 1D -> Example -> shuosher_teno5
C7598989 1.62 1D -> Example -> acoustic_sine_frequency
E49EF7B6 7.94 3D -> Example -> IGR_TaylorGreenVortex
C7927D03 3.17 2D -> Example -> jet
8DA238FF 4.46 3D -> Example -> brio_wu
99147C82 1.79 2D -> Example -> ibm_stl_test |
Sure thing, I will push all docs to the PR tonight. Other than that, no changes to be made to the PR code, just existing MFC docs & README. |
yeah all of this should be documented. though the M-series mac chips should work out of the box since so many people run those. there should be M-series github runners for free, no? |
List of GitHub runner https://docs.github.com/en/actions/reference/runners/github-hosted-runners Linuxx64 ubuntu-latest, ubuntu-24.04, ubuntu-22.04 Windowsx64 windows-latest, windows-2025, windows-2022 macOSIntel macos-13, macos-15-intel macOSarm64 macos-latest, macos-14, macos-15, macos-26 (public preview) Genuinely idk how it is gonna turn out but I will try to containerize with matrix:
config:
- { name: 'cpu', runner: 'ubuntu-22.04', base_image: 'ubuntu:22.04' }
- { name: 'cpu', runner: 'ubuntu-22.04-arm', base_image: 'ubuntu:22.04' }
- { name: 'gpu', runner: 'ubuntu-22.04', base_image: 'nvcr.io/nvidia/nvhpc:23.11-devel-cuda12.3-ubuntu22.04' }
- { name: 'gpu', runner: 'ubuntu-22.04-arm', base_image: 'nvcr.io/nvidia/nvhpc:23.11-devel-cuda12.3-ubuntu22.04' } |
|
I guess my main view is that someone on Apple silicon laptops/devices should be able to use the container without any issues. If that means adding another container, or using an ubuntu-based one, I'm not sure. |
3 participants
User description
Description
Replacing (#935), since it was overly inefficient workflow without yielding any tangible advantages.
Notes to Self:
Containerization of MFC Releases (v4.3.0-v5.0.5)
https://github.com/Malmahrouqi3/MFC-mo2.git --branch docker, and add credentials to its GitHub secrets.release.yml), then hit Run workflow and specify a range of desired releases. Except the first few published releases where--gpuflag was not defined yet, the rest should build without any issues. Repeated use of Release Dispatcher for debugging could exhaust docker limits.e.g. "You have reached your pull rate limit as"
Setup MFC Container on Codespaces
This is intended to pre-configure repo codespace instances to load MFC docker container for users to interact with instantaneously.
.devcontainerfolder in the repo root, and add adevcontainer.jsonfile.{ "name": "MFC Dev Container", "image": "sbryngelson/mfc:<tag>", "workspaceFolder": "/opt/MFC", "settings": { "terminal.integrated.shell.linux": "/bin/bash", "editor.formatOnSave": true }, }Quick Start Guide
GitHub Codespaces
Locally
User Guide
Make sure to mount a directory to
mntinside the container to easily share files between the host and the container, e.g.cp -r <source> /mnt/.Docker CLI
Official Documentation
Use it for running and testing containers on your local machine.
Example Usage:
For Portability,
On the source machine,
On the target machine,
Apptainer CLI
Official Documentation
Use it for running containers on powerful machines and HPC clusters on either interactive terminals or batch jobs.
Example Usage:
or
--fakeroot --writable-tmpfsis critical to:For Portability,
On the source machine,
.sifformatOn the target machine,
PR Type
Enhancement
Description
Add Docker containerization support for MFC
Create CPU and GPU container variants
Implement automated container builds on releases
Configure Docker Hub deployment workflow
Diagram Walkthrough
File Walkthrough
.dockerignore
Docker ignore configuration for clean builds.github/.dockerignore
Dockerfile
Multi-architecture Dockerfile for MFC containers.github/Dockerfile
docker.yml
Automated container build and deployment workflow.github/workflows/docker.yml
PR Type
Enhancement
Description
Add Docker containerization support for MFC releases
Create GitHub Actions workflow for automated container builds
Configure development container for Codespaces integration
Support both CPU and GPU container variants
Diagram Walkthrough
File Walkthrough
devcontainer.json
Add Codespaces development container configuration.devcontainer/devcontainer.json
.dockerignore
Add Docker ignore file for build optimization.github/.dockerignore
Dockerfile
Add Dockerfile for MFC containerization.github/Dockerfile
docker.yml
Add GitHub Actions workflow for container builds.github/workflows/docker.yml
Note
Adds Dockerfile and CI workflow to build/push CPU/GPU images and a Codespaces devcontainer configuration.
/.github/workflows/docker.yml: Matrix builds forcpu/gpuon x86/arm; sets up Buildx/QEMU; clones release tag; builds with compiler/base-image args; pushes to Docker Hub; creates/pushes multi-platform manifest lists (cpu,gpu,latest-*)./.github/Dockerfile: Parametric base image and compilers; conditional deps forcpuvsgpu; builds MFC and runs dry-run tests; setsOMPI_*,PATH,LD_LIBRARY_PATH; stages repo in/opt/MFCand sets default workdir/entrypoint./.github/.dockerignore: Excludes build artifacts, caches, example outputs, and large media from build context./.devcontainer/devcontainer.json: Codespaces devcontainer using publishedsbryngelson/mfc:*image with workspace and editor settings.Written by Cursor Bugbot for commit bea47ca. This will update automatically on new commits. Configure here.