7. FEniCS development using Docker¶

The FEniCS Docker images provide a convenient environment for FEniCS development since the images provide all FEniCS dependencies. Follow the instructions below to create an environment that let’s you pull, push, edit and build FEniCS using Docker.

7.1. Development quickstart¶

On the host:

curl -s https://get.fenicsproject.org | bash
export FENICS_SRC_DIR=$HOME/dev/fenics
mkdir -p $FENICS_SRC_DIR
cd $FENICS_SRC_DIR
for p in fiat instant dijitso ufl ffc dolfin mshr; do git clone git@bitbucket.org:fenics-project/$p.git; done
fenicsproject pull dev-env
fenicsproject create my-dev-env dev-env
fenicsproject start my-dev-env

Inside the container:

fenics-build

The workflow is to edit the code and interact with the git repositories on the host with your favourite tools, and then build and run FEniCS inside the container.

7.2. Install the `fenicsproject` script¶

curl -s https://get.fenicsproject.org | bash

While it is possible to use straight docker commands to launch a development container, the script makes things significantly easier. Read on for full details: Install the fenicsproject script.

7.3. Set up your FEniCS source tree¶

We will set up the FEniCS source tree on the host. This means you can use all of your usual development tools, like vim or emacs on the host, and just do the compilation and execution inside the container. You should also use git push and git pull on the host so that you can use your usual git SSH keys and setup.

We need to make a folder, e.g. $HOME/dev/fenics on the host system to hold the FEniCS source code:

export FENICS_SRC_DIR=$HOME/dev/fenics
mkdir -p $FENICS_SRC_DIR

You can make this setup permanent by setting the environment variable export FENICS_SRC_DIR=$HOME/dev/fenics in your $HOME/.profile or similar file. Feel free to choose another directory for your FEniCS sources.

7.4. Pull the FEniCS sources¶

cd $FENICS_SRC_DIR
git clone git@bitbucket.org:fenics-project/fiat.git
git clone git@bitbucket.org:fenics-project/instant.git
git clone git@bitbucket.org:fenics-project/dijitso.git
git clone git@bitbucket.org:fenics-project/ufl.git
git clone git@bitbucket.org:fenics-project/ffc.git
git clone git@bitbucket.org:fenics-project/dolfin.git
git clone git@bitbucket.org:fenics-project/mshr.git

Alternatively, the following short form can be used in place of the string of clones:

for p in fiat instant dijitso ufl ffc dolfin mshr; do git clone git@bitbucket.org:fenics-project/$p.git; done

Note that we pull the sources from outside the Docker container (which we have yet to create). This ensures that we pull using the ssh protocol (rather than the https protocol) and it ensures that you can interact with the repositories using your normal credentials (keys) on the host system. If you are using other repositories than the standard ones (in particular forks not owned by fenics-project), make suitable adjustments to the git clone commands above.

7.5. Create the Docker container¶

We will now setup the development container using the fenicsproject script.

fenicsproject pull dev-env
cd $FENICS_SRC_DIR
fenicsproject create my-dev-env dev-env

The first command pulls the latest FEniCS dev-env image containing all the dependencies you need for building FEniCS such as PETSc and MPI. This will happen automatically when you run the fenicsproject create command below, but if you have previously used the dev-env image, make sure to run the fenicsproject pull command to get the very latest version of the dev-env image.

The second command enters the FEniCS source directory. This is not strictly necessary for our purposes, but the fenicsproject script will complain if the fenicsproject create command is issued from the home directory. Feel free to enter some other directory which will then be shared to $HOME/shared inside the Docker container. The source directory will automatically be shared anyway at $HOME/local/src.

The third command creates a container named my-dev-env that you will be using for FEniCS development. You may of course choose another name for this container.

7.6. Start the FEniCS Docker container¶

fenicsproject start my-dev-env

This command will fire up the Docker container and we are ready to get going. The FEniCS source directory that we created previously will be shared into the directory $HOME/local/src inside the container.

7.7. Build FEniCS inside the Docker container¶

To build all of the FEniCS components from the source you have shared into the container, simply run the following command inside the container:

fenics-build

Both commands build all the sources residing in $HOME/local/src and install the results into $HOME/local. Once all components have been built, you may run FEniCS programs without changing any paths or setting any other environment variables. Everything is already setup correctly to point at the $HOME/local installation directory.

Note that there is also a command named fenics-pull. This will pull all the FEniCS sources into $HOME/local/src by entering each source directory and calling git pull. This means that the command will pull the sources for the default remote for the particular branch that each repository happens to be located at.

During development, you will likely need to rebuild and install a particular component repeatedly. For example, to re-build ffc:

fenics-build ffc