Run fidimag inside a Docker Container¶

Setup Docker¶

Install Docker, follow instructions at https://www.docker.com/products/docker

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 192.168.99.100, then the right URL to paste into the browser on the host system is http://192.168.99.100:30000.

[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):

jovyan@4df962d27520:~/work$

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 run.py 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 run.py`

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 run.py 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 hello.py

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 https://github.com/computationalmodelling/fidimag.git
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.

User Guide Fidimag: A Basic Simulation