Feel++

Docker

Docker is the recommended way if you are beginning using Feel++.

This chapter explains step by step how to get the Feel++ Container System(FCS), how to execute a precompiled application, how to parameter and run models.

Introduction

Container based technologies are revolutionizing development, deployment and execution of softwares. Containers encapsulate a software and allow to run seamlessly on different platforms — clusters, workstations, laptops — The developer doesn’t have to worry about specific environments and users spend less time in configuring and installing the software. Containers appear to be lightweight virtual machines (VMs) — they are started in a fraction of a second — but they, in fact, have important differences.

One of the differences is the isolation process. The VMs share only the hypervisor, the OS and hardware whereas containers may share, between each other, large parts of filesystems rather than having copies. Another difference is that, unlike in VMs, processes in a container are similar to native processes and they do not incur the overhead due to the VM hypervisor. The figure below illustrates these fundamental differences. We see in particular that the applications 2 and 3 are sharing lib 2 without redundancy.

Figure 1. Figure : VMs vs Containers

Docker is a container technology providing:

  1. an engine to start and stop containers,

  2. a user friendly interface from the creation to the distribution of containers and

  3. a hub  — cloud service for container distribution — that provides publicly a huge number of containers to download and avoid duplicating work.

Installation

This section covers briefly the installation of Docker. It should be a relatively simple smooth process to install Docker.

Channels

Docker offers two channels: the stable and beta channels.

stable channel

is fully baked and tested software providing a reliable platform to work with. Releases are not frequent.

beta channel

offers cutting edge features and experimental versions of the Docker Engine. This is a continuation of the initial Beta program of Docker to experiment with the latest features in development. It incurs far more instabilities than the stable channel but releases are done frequently — possibly several releases per month.

In the latter we shall consider only installing and using the stable channel.

Installing Docker

At the time of writing this section, Docker is available on Linux, Mac and Windows.

Mac and Windows

The support for Mac and Windows as Host OS was recently released and Docker Inc provides installation processes Docker For Mac and Docker for Windows which are the recommended way of installing Docker on these platforms.

Linux

Most Linux distributions have their own packages but they tend to lag behind the stable releases of Docker which could be a serious issue considering the development speed of Docker.

To follow Docker releases, it is probably best to use the packages distributed by Docker.

Installing Binaries

The last possibility is to use Docker Binaries to install Docker. This should be used at the last resort if packages are provided neither by your distribution nor by Docker Inc.

Tested with Docker 1.12

At the time of writing this book, the Docker version we used is Docker 1.12. All commands have been tested with this version.

Running without sudo

On Linux, Docker is a priviledged binary, you need to prefix all your commands with sudo, e.g. on Ubuntu. You need first to belong to the docker group with the following command on Ubuntu

$ sudo usermod -aG docker

It creates the docker group if it doesn’t already exist and adds the current user to the docker group. Then you need to log out and log in again. Similar process is available on other distributions. You need also to restart the docker service

$ sudo service docker restart
From now on, we omit the sudo command when using Docker for the sake of brevity.
Adding a user to the docker group has security implications. On a shared machine, you should consider reading the Docker security page.

Checking Docker

We now check your installation by running docker version To make sure everything is installed correctly and working, try running the docker version command. You should see something like the following on Linux or Mac.

Listing : Output of docker version on Linux
> docker version
Client:
 Version:      1.12.1
 API version:  1.24
 Go version:   go1.6.3
 Git commit:   23cf638
 Built:        Mon, 10 Oct 2016 21:38:17 +1300
 OS/Arch:      linux/amd64

Server:
 Version:      1.12.1
 API version:  1.24
 Go version:   go1.6.3
 Git commit:   23cf638
 Built:        Mon, 10 Oct 2016 21:38:17 +1300
 OS/Arch:      linux/amd64
Listing : Output of docker version on Mac
> docker version
Client:
Version: 1.12.6
API version: 1.24
Go version: go1.6.4
Git commit: 78d1802
Built: Wed Jan 11 00:23:16 2017
OS/Arch: darwin/amd64

Server:
Version: 1.12.6
API version: 1.24
Go version: go1.6.4
Git commit: 78d1802
Built: Wed Jan 11 00:23:16 2017
OS/Arch: linux/amd64

If so, you are ready for the next step. If instead you get something like

Listing : Bad response output of docker version on Linux
> docker version
Client:
 Version:      1.12.1
 API version:  1.24
 Go version:   go1.6.3
 Git commit:   23cf638
 Built:        Mon, 10 Oct 2016 21:38:17 +1300
 OS/Arch:      linux/amd64
Cannot connect to the Docker daemon. Is the docker daemon running on this host?
Listing : Bad response output of docker version on Mac
> docker version
Client:
 Version:      1.12.6
 API version:  1.24
 Go version:   go1.6.4
 Git commit:   78d1802
 Built:        Wed Jan 11 00:23:16 2017
 OS/Arch:      darwin/amd64
Error response from daemon: Bad response from Docker engine

then it means that the Docker daemon is not running or that the client cannot access it.

To investigate the problem you can try running the daemon manually — e.g. sudo docker daemon. This should give you some informations of what might have gone wrong with your installation.

Feel++ Containers

Feel++ leverages the power of Docker and provides a stack of container images.

First steps

To test Docker is installed properly, try

$ docker run feelpp/feelpp-env  echo 'Hello World!'

We have called the docker run command which takes care of executing containers. We passed the argument feelpp/feelpp-env which is a Feel++ Ubuntu 16.10 container with the required programming and execution environment for Feel++.

feelpp/ in feelpp/feelpp-env provides the organization name (or namespace) of the image and feelpp-env is the image name. Note also that Docker specifies a more complete name feelpp/feelpp-env:latest including the tag name :latest. We will see later how we defined the latest tag at the Feel++ organization. See Feel++ Container System for more details.

This may take a while depending on your internet connection but eventually you should see something like

Unable to find image 'feelpp/feelpp-env:latest' locally (1)
latest: Pulling from feelpp/feelpp-env
8e21f82d32cf: Pull complete
[...]
0a8dee947f9b: Pull complete
Digest: sha256:457539dbd781594eccd4ddf26a7aefdf08a2fff9dbeb1f601a22d9e7e3761fbc
Status: Downloaded newer image for feelpp/feelpp-env:latest
Hello World!
1 The first line tells us that there is no local copy of this Feel++ image. Docker checks automatically online on the Docker Hub if an image is available.

Once the image is downloaded, Docker launches the container and executes the command we provided echo 'Hello World!' from inside the container. The result of the command is showed on the last line of the output log above.

If you run the command again, you won’t see the download part and the command will be executed very fast.

We can ask Docker to give us a shell using the following command

$ docker run -it feelpp/feelpp-env

It provides a shell prompt from inside the container which is very similar to what you obtain when login with ssh on a remote machine. The flags -i and -t tell Docker to provide an interactive session (-i) with a TTY attached (-t).

Feel++ Container System

The Feel++ Container System (FCS) is organized in layers and provides a set of images.

Naming

The naming convention of the FCS allows the user to know where they come from and where they are stored on the Docker Hub. The name of the images is built as follows

feelpp/feelp-<component>[:tag]

where

  • feelpp/ is the namespace of the image and organization name

  • feelpp-<component> the image name and Feel++ component

  • [:tag] an optional tag for the image, by default set to :latest

Feel++ images(components) are defined as layers in the FCS in the table below.

Table 1. Table of the current components of the FCS
Component Description Built From

feelpp-env

Execution and Programming environment

<OS>

feelpp-libs

Feel++ libraries and tools

feelpp-env

feelpp-base

Feel++ base applications

feelpp-libs

feelpp-toolboxes

Feel++ toolboxes

feelpp-toolboxes

| Note: feelpp-env depends on an operating system image <OS>, the recommended and default <OS> is Ubuntu 16.10. In the future, we will build upon the next Ubuntu LTS or Debian Stable releases.

Tags

By default, the :latest tag is assumed in the name of the images, for example when running

$ docker run -it feelpp/feelpp-base

it is in fact feelpp/feelpp-base:latest which is being launched. The following table displays how the different images depend from one another.

Image Built from

feelpp-env:latest

Ubuntu 16.10

feelpp-libs:latest

feelpp-env:latest

feelpp-base:latest

feelpp-libs:latest

feelpp-toolboxes:latest

feelpp-base:latest

Host OS

As we said before the default Host OS is Ubuntu 16.10. However Docker shines in continuous integration. It provides a large set of operating system to build upon and allows to check the software in various contexts. The FCS takes advantage of Docker to build feelpp-libs for several operating systems provided by feelpp-env and with different compilers any time a commit in the Feel++ repository is done.

Table 2. Table providing the list of supported Host OS
Operating system version feelpp-env Tags Compilers

Ubuntu

16.10

ubuntu-16.10, latest

GCC 6.x, Clang 3.9

Ubuntu

16.04

ubuntu-16.04

GCC 6.x, Clang 3.8

Debian

sid

debian-sid

GCC 6.x, Clang 3.9,4.0

Debian

testing

debian-testing

GCC 6.x, Clang 3.9

If you are interested in testing Feel++ in these systems, you can run these flavors.

Containers

feelpp-env

feelpp-env provides the Host OS and Feel++ dependencies.

$ docker run feelpp/feelpp-env

feelpp-libs

feelpp-libs builds from feelpp-env and provides:

  1. the Feel++ libraries

  2. the Feel++ mesh partitioner application

$ docker run feelpp/feelpp-libs

feelpp-base

feelpp-base builds from feelpp-libs and provides two basic applications:

  1. feelpp_qs_laplacian_*: 2D and 3D laplacian problem

  2. feelpp_qs_stokes_*: 2D stokes problem

$ docker run feelpp/feelpp-base

feelpp-toolboxes

feelpp-toolboxes builds from feelpp-base and provides

$ docker run feelpp/feelpp-toolboxes

Running Feel++ Applications

To run Feel++ applications in docker, you need first to create a directory where you will store the Feel++ simulation files. For example, type

> mkdir $HOME/feel

and then type the following docker command

> docker run -it -v $HOME/feel:/feel feelpp/feelpp-libs

The previous command will execute the latest feelpp/feelpp-libs docker image in interactive mode in a terminal (-ti) and mount $HOME/feel in the directory /feel of the docker image.

Running the command df inside the Docker container launched by the previous command

feelpp@4e7b485faf8e:~$ df

will get you this kind of output

Filesystem     1K-blocks      Used Available Use% Mounted on
none           982046716 505681144 426457452  55% /
tmpfs          132020292         0 132020292   0% /dev
tmpfs          132020292         0 132020292   0% /sys/fs/cgroup
/dev/sda2      982046716 505681144 426457452  55% /feel
shm                65536         0     65536   0% /dev/shm

You see on the last but one line the directory $HOME/feel mounted on /feel in the Docker image.

Note that mouting a host sub-directory on /feel is mandatory. If you don’t, the Feel++ applications will exit due to lack of permissions. If you prefer running inside the docker environment you can type unset FEELPP_REPOSITORY and then all results from Feel++ applications will be store in $HOME/feel. But then you will have to use `rsync or ssh to copy your results out of the docker image if needed.