Run fidimag inside a Docker Container

Setup Docker

Install Docker, follow instructions at

Setup fidimag docker container with Jupyter Notebook

Pull the fidimag notebook container:

docker pull fidimag/notebook

Start Notebook on container

docker run -p 30000:8888 fidimag/notebook

This command starts a Jupyter Notebook in which `fidimag <>`__ can be used. The Jupyter notebook inside the container is listening on port 8888.

The parameter -p 30000:8888 says that the port 8888 inside the container is exposed on the host system as port 30000.

On a Linux host machine, you can connect to http://localhost:30000 to see the notebook.

On a Mac, you need to find out the right IP address to which to connect. The information is provided by

docker-machine ip

For example, if docker-machine ip returns, then the right URL to paste into the browser on the host system is

[How does this work on Windows? Pull requests welcome.]

Detach the docker image (to run in the background)

You can add the -d switch to the docker run command to detach the process:

docker run -d -p 30000:8888 fidimag/notebook

Show active Docker containers

docker ps lists all running containers.

To only show the ids, we can use

docker ps -q

To only show the containers that was last started, we can use the -l flag:

docker ps -l

Stop a docker container

To stop the last container started, we can use the docker stop ID command, where we need to find the ID first. We can do this using docker ps -l -q. Putting the commands together, we have

docker stop $(docker ps -l -q)

to stop the last container we started.

Explore the docker container / run Fidimag from (I)Python

We can start the docker container with the -ti switch, and we can provide bash as the command to execute:

docker run -ti fidimag/notebook bash

A bash prompt appears (and we are now inside the container):


and can start Python inside the container, and import fidimag:

jovyan@4df962d27520:~/work$ python
Python 3.5.1 |Continuum Analytics, Inc.| (default, Jun 15 2016, 15:32:45)
[GCC 4.4.7 20120313 (Red Hat 4.4.7-1)] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import  fidimag

We could also start IPython:

jovyan@4df962d27520:~/work$ ipython
Python 3.5.1 |Continuum Analytics, Inc.| (default, Jun 15 2016, 15:32:45)
Type "copyright", "credits" or "license" for more information.

IPython 4.2.0 -- An enhanced Interactive Python.
?         -> Introduction and overview of IPython's features.
%quickref -> Quick reference.
help      -> Python's own help system.
object?   -> Details about 'object', use 'object??' for extra details.

In [1]:

[The switch -t stands for Allocate a pseudo-TTY and -i for Keep STDIN open even if not attached.]

Mount the local file system to exchange files and data with container

Often, we may have a fidimag Python script we want to execute in our current working directory in the host machine. We want output files from that command to be written to the same working directory on the host machine.

We can use the container like this to achieve that:

docker run -v `pwd`:/io -ti fidimag/notebook python

The -v `pwd`:/io tells the docker container to take the current working directory on the host (`pwd`) and mount it to the path /io on the container. The container is set up so that the default working directory is /io.

Here is an example file that reads

import fidimag   # to proof we can import it
print("Hello from the container")
# and write to a file
open("data.txt", "w").write("Data from the container.\n")

This can be executed with

docker run -v `pwd`:/io -ti fidimag/notebook python

and will create a data file data.txt that is visible from the host’s working directory.

Explore Jupyter notebook examples with the Docker container

git clone
cd fidimag/doc/ipynb/
docker run -v `pwd`:/io -p 30000:8888 -d fidimag/notebook

Use smaller docker containers

Two alternative docker containers are available that provide only Fidimag, but not the Jupyter Notebook, nor scipy. They are available under the names fidimag/minimal-py2 and fidimag/minimal-py3. Use these names instead of fidimag/notebook in the examples above.

The fidimag/minimal-py2 version uses Python2, the fidimag/minimal-py3 version uses Python 3.