2. Introduction¶
Note
Want to get up and running quickly? Try the
fenicsproject
script in Quickstart.
Docker allows FEniCS and its dependencies to be packaged into a standard format for identical deployment almost anywhere. Docker containers are lightweight and are based on open standards that run on all major Linux distributions, macOS and Microsoft Windows platforms. For more information, visit https://www.docker.com/what-docker.
2.1. Installing Docker¶
Install Docker by following these instructions.
If using the Docker Toolbox (macOS versions < 10.10 or Windows versions < 10), make sure you run all commands inside the Docker Quickstart Terminal.
2.2. Running FEniCS in Docker¶
Under macOS or Windows, start a Docker Quickstart Terminal.
For Linux, use a standard terminal. You may need to prepend sudo
to
the commands below. In addition, if you are executing docker via
fenicsproject
script, you must prepend it with sudo -E
. This
flag allows sudo
to see the enviromental variables, such as
$FENICS_SRC_DIR
. To allow sudo
-less use, refer to the
installation instructions for your distribution to add your user to the
docker
group.
First check that Docker is working:
docker run hello-world
You should see a message saying that your Docker installation is working correctly.
Note
Not working? Check out the Troubleshooting section.
To pull
the quay.io/fenicsproject/stable
image:
docker pull quay.io/fenicsproject/stable:latest
To start FEniCS, run:
docker run -ti quay.io/fenicsproject/stable:latest
You will be presented with a prompt where you can run FEniCS:
fenics@0521831b5f28:~$
fenics
is your username inside the container and the number
0521831b5f28
is the CONTAINER ID
that Docker has assigned.
This ID is unique to your computer and this container and will be
different to the one above.
The DOLFIN poisson.py
example can be run using:
cd ~/demo/documented/poisson/python
python3 demo_poisson.py
The results will be outputted to the file poisson.pvd
in the same
directory. How to open this file with a visualisation tool is covered in
the next section.
2.3. Sharing files from the host into the container¶
Most users want to continue using the text editor, version control and other tools already installed on their computers, and just use the Docker container to run FEniCS.
To share files between the host system and the container, use:
docker run -ti -v $(pwd):/home/fenics/shared quay.io/fenicsproject/stable
Note
Users running Linux distributions with SELinux enabled
(Redhat, CentOS, Fedora, and others) will need to add the :z
option to all subsequent host volume mounts -v
, e.g.:
docker run -ti -v $(pwd):/home/fenics/shared:z quay.io/fenicsproject/stable
Note
Permissions issues on Linux? Check out the Troubleshooting section.
This command will run
a new container with the current working
directory $(pwd)
shared with the container at the path
/home/fenics/shared
from inside the container.
The syntax for the argument -v
is
/path/on/host:/path/in/container
. Note that all paths are
absolute paths.
Now, you can edit your code on the host and run the following inside the container:
cd $HOME/shared
python3 my_code.py
In this case, all files in my-work-directory
will be shared into
the container. Any files you place in the directory
/home/fenics/shared
in the container will be available on the host
system at the current working directory $(pwd)
, and vice versa. We
recommend keeping the source code and generated results for your
projects in this shared directory, easily accessible on the host
machine.
Any files placed in any other directory than /home/fenics/shared
in the container will remain in the container and are not accessible
on the host.
2.4. Naming a container¶
Every container can be given a name so it can be easily referred to it
in the future by passing the --name
flag to the docker run
command, e.g.:
docker run -ti -v $(pwd):/home/fenics/shared --name fenics-container quay.io/fenicsproject/stable
The container can be be stopped and started:
docker stop fenics-container
docker start fenics-container
docker exec -ti -u fenics fenics-container /bin/bash -l
To see the name and other information of every container you have ever created:
docker ps -a
To see the information of only running containers:
docker ps
For more details on ways of working with Docker and FEniCS, check out Suggested workflows.