mfem · tzanio · May 13, 2022 · Apr 27, 2022 · Apr 27, 2022 · Apr 27, 2022
diff --git a/.github/workflows/build-container.yaml b/.github/workflows/build-container.yaml
@@ -0,0 +1,80 @@
+name: Build Deploy Container
+
+on:
+
+  # Always have a base image ready to go - this is a nightly build
+  schedule:
+    - cron: 0 3 * * *
+
+  # Allow manual trigger of a build
+  workflow_dispatch:
+
+  # On push to main we build and deploy images
+  push:
+    branches:
+      - master
+
+  # Publish packages on release
+  release:
+    types: [published]
+
+jobs:
+  build:
+    permissions:
+      packages: write
+    strategy:
+      fail-fast: false
+      matrix:
+
+        # Dockerfiles to build, a matrix supports future expanded builds
+        container: [["config/docker/Dockerfile", "ghcr.io/mfem/mfem-ubuntu-base"]]
+
+    runs-on: ubuntu-latest
+    name: Build
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Make Space For Build
+        run: |
+          sudo rm -rf /usr/share/dotnet
+          sudo rm -rf /opt/ghc
+
+       # It's easier to reference named variables than indexes of the matrix
+      - name: Set Environment
+        env:
+          dockerfile: ${{ matrix.container[0] }}
+          uri: ${{ matrix.container[1] }}
+        run: |
+          echo "dockerfile=$dockerfile" >> $GITHUB_ENV
+          echo "uri=$uri" >> $GITHUB_ENV
+
+      - name: Pull previous layers for cache
+        run: docker pull ${uri}:latest || echo "No container to pull"
+
+      - name: Build Container
+        run: |
+           container=$uri:latest
+           docker build -f ${dockerfile} -t ${container} .
+           echo "container=$container" >> $GITHUB_ENV
+
+      - name: GHCR Login
+        if: (github.event_name != 'pull_request')
+            uses: docker/login-action@v1
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Deploy
+        if: (github.event_name != 'pull_request')
+        run: |
+            docker push ${container}
+
+      - name: Tag and Push Release
+        if: (github.event_name == 'release')
+        run: |
+            tag=${GITHUB_REF#refs/tags/}
+            echo "Tagging and releasing ${uri}:${tag}"
+            docker tag ${uri}:latest ${uri}:${tag}
+            docker push ${uri}:${tag}
diff --git a/CHANGELOG b/CHANGELOG
@@ -31,6 +31,7 @@ Version 4.4.1 (development)
 - Add a new example code, Example 33/33p, to demonstrate the solution of
   spectral fractional PDEs with MFEM.
 
+- Added a Dockerfile for a simple MFEM container, see config/docker/README.md
 - Added support for assembling low-order-refined matrices using a GPU-enabled
   "batched" algorithm. The lor_solvers and plor_solvers now fully support GPU
   acceleration.

diff --git a/README → README.md b/README → README.md
@@ -1,3 +1,4 @@
+```
                     Finite Element Discretization Library
                                    __
                        _ __ ___   / _|  ___  _ __ ___
@@ -7,21 +8,25 @@
 
                                https://mfem.org
 
+```
+
 MFEM is a modular parallel C++ library for finite element methods. Its goal is
 to enable high-performance scalable finite element discretization research and
 application development on a wide variety of platforms, ranging from laptops to
 supercomputers.
 
 We welcome contributions and feedback from the community. Please see the file
-CONTRIBUTING.md for additional details about our development process.
+[CONTRIBUTING.md](CONTRIBUTING.md) for additional details about our development process.
 
-* For building instructions, see the file INSTALL, or type "make help".
+* For building instructions, see the file [INSTALL](INSTALL), or type "make help".
 
 * Copyright and licensing information can be found in files LICENSE and NOTICE.
 
 * The best starting point for new users interested in MFEM's features is to
   review the examples and miniapps at https://mfem.org/examples.
 
+* Instructions for learning with Docker are in [config/docker](config/docker).
+
 Conceptually, MFEM can be viewed as a finite element toolbox that provides the
 building blocks for developing finite element algorithms in a manner similar to
 that of MATLAB for linear algebra methods. In particular, MFEM provides support
@@ -61,6 +66,8 @@ additional linear and nonlinear solvers, preconditioners, time integrators, etc.
 For examples of using MFEM, see the examples/ and miniapps/ directories, as well
 as the OpenGL visualization tool GLVis which is available at https://glvis.org.
 
+## License
+
 MFEM is distributed under the terms of the BSD-3 license. All new contributions
 must be made under this license. See LICENSE and NOTICE for details.
 

diff --git a/config/docker/Dockerfile b/config/docker/Dockerfile
@@ -0,0 +1,30 @@
+FROM ghcr.io/rse-ops/cuda-ubuntu-20.04:cuda-11.0.3
+
+# docker build -t ghcr.io/mfem/mfem-ubuntu-base .
+
+RUN apt-get update && \
+    apt-get install -y unzip gfortran && \
+    spack compiler find && \
+    apt-get install -y libcurl4-openssl-dev libssl-dev
+
+# /code is the working directory for code
+WORKDIR /code
+COPY . /code
+
+# This is for a spack environment/view to install from there
+WORKDIR /opt/mfem-env
+RUN . /opt/spack/share/spack/setup-env.sh && \
+    spack env create -d . && \
+    echo "  concretization: together" >> spack.yaml && \
+    spack env activate . && \
+    spack develop --path /code mfem@master+examples+miniapps && \
+    spack add mfem@master+examples+miniapps && \
+    spack install
+
+# ensure mfem always on various paths
+RUN cd /opt/mfem-env && \
+    spack env activate --sh -d . >> /etc/profile.d/z10_spack_environment.sh
+
+# The user will see the view on shell into the container
+WORKDIR /opt/mfem-env/.spack-env/view/
+ENTRYPOINT ["/bin/bash", "--rcfile", "/etc/profile", "-l", "-c"]
diff --git a/config/docker/README.md b/config/docker/README.md
@@ -0,0 +1,130 @@
+# mfem Docker
+
+We provide a [Dockerfile](Dockerfile) to build an ubuntu base image. You can use
+this image for a demo of using mfem! 🎉️
+
+Updated containers are built and deployed on merges to the main branch and releases.
+If you want to request a build on demand, you can [manually run the workflow](https://docs.github.com/en/actions/managing-workflow-runs/manually-running-a-workflow) thanks to the workflow dispatch event.
+
+### Usage
+
+Here is how to build the container. Note that we build so it belongs to the same
+namespace as the repository here. "ghcr.io" means "GitHub Container Registry" and
+is the [GitHub packages](https://github.com/features/packages) registry that supports
+ Docker images and other OCI artifacts. From the root of the repository:
+
+```bash
+$ docker build -f config/docker/Dockerfile -t ghcr.io/mfem/mfem-ubuntu-base .
+```
+
+or this directory:
+
+```bash
+$ docker build -f Dockerfile -t ghcr.io/mfem/mfem-ubuntu-base ../../
+```
+
+### Shell
+
+To shell into a container (here is an example with ubuntu):
+
+```bash
+$ docker run -it ghcr.io/mfem/mfem-ubuntu-base bash
+```
+
+Off the bat, you can see mfem libraries are in your path so you can jump into development:
+
+```bash
+env | grep mfem
+```
+```bash
+PKG_CONFIG_PATH=/opt/mfem-env/.spack-env/view/lib/pkgconfig:/opt/mfem-env/.spack-env/view/share/pkgconfig:/opt/mfem-env/.spack-env/view/lib64/pkgconfig
+PWD=/opt/mfem-env
+MANPATH=/opt/mfem-env/.spack-env/view/share/man:/opt/mfem-env/.spack-env/view/man:
+CMAKE_PREFIX_PATH=/opt/mfem-env/.spack-env/view
+SPACK_ENV=/opt/mfem-env
+ACLOCAL_PATH=/opt/mfem-env/.spack-env/view/share/aclocal
+LD_LIBRARY_PATH=/opt/mfem-env/.spack-env/view/lib:/opt/mfem-env/.spack-env/view/lib64
+PATH=/opt/mfem-env/.spack-env/view/bin:/opt/view/bin:/opt/spack/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
+```
+
+#### Examples and MiniApps
+
+If you want to develop a tool that _uses_ mfem, you can find the built libraries in:
+
+```
+$ ls /opt/mfem-env/.spack-env/view/
+bin  etc  include  lib  libexec  sbin  share  var
+```
+
+And yes, this is the working directory when you shell into the container!
+You can find the examples here:
+
+
+```bash
+cd share/mfem/examples
+```
+```bash
+$ ./ex0
+Options used:
+   --mesh ../data/star.mesh
+   --order 1
+Number of unknowns: 101
+   Iteration :   0  (B r, r) = 0.184259
+   Iteration :   1  (B r, r) = 0.102754
+   Iteration :   2  (B r, r) = 0.00558141
+   Iteration :   3  (B r, r) = 1.5247e-05
+   Iteration :   4  (B r, r) = 1.13807e-07
+   Iteration :   5  (B r, r) = 6.27231e-09
+   Iteration :   6  (B r, r) = 3.76268e-11
+   Iteration :   7  (B r, r) = 6.07423e-13
+   Iteration :   8  (B r, r) = 4.10615e-15
+Average reduction factor = 0.140201
+```
+
+Try running a few, and look at the associated .cpp file for the source code!
+You can also explore the "mini apps," also in share/mfem, but under miniapps.
+
+```bash
+# This is run from the examples directory
+$ cd ../miniapps
+```
+```bash
+$ ls
+CMakeLists.txt  common            meshing  nurbs        shifted  toys
+adjoint         electromagnetics  mtop     parelag      solvers
+autodiff        gslib             navier   performance  tools
+```
+
+And an example in "toys"
+
+```bash
+cd toys
+```
+```bash
+$ ./automata -no-vis
+Options used:
+   --num-steps 16
+   --rule 90
+   --no-visualization
+
+Rule:
+ 111 110 101 100 011 010 001 000
+  0   1   0   1   1   0   1   0
+
+Applying rule...done.
+```
+
+Have fun!
+
+
+#### Your own App
+If you want to develop with your own code base
+(and mfem as is in the container) you can bind to somewhere else in the container (e.g., src)
+
+```bash
+$ docker run -it ghcr.io/mfem/mfem-ubuntu-base -v $PWD:/src bash
+```
+
+In the above, we can pretend your project is in the present working directory (PWD) and we are
+binding to source. You can then use the mfem in the container for development, and if you
+want to distribute your library or app in a container, you can use the mfem container as the base.