Docker

We use Docker to create a reliable cross-platform environment in which our exhaustive test battery can run.

Installation

Download the appropriate Docker engine here.

Warning

You cannot install Docker on Windows 10 Home and on older MacOS. Choose the Docker Toolbox instead.

Build the image

In order to build the image with the current respy version in the repository, cd to the respy folder and type

$ docker build -t respy

Warning

On Linux systems you will need sudo permissions for docker build

To be clear, the image is built with the respy version in the directory using pip install .. Unfortunately, this means that you have to rebuild the image every time you change something in the code. Since Docker creates layers during builds which are essentially snapshots after each statement in the Dockerfile, this is not as costly as it sounds.

Enter the container interactively

Type

$ docker run -it respy

Warning

On Linux systems you will need sudo permissions for docker run

to enter the container and open a bash terminal. The conda environment is already activated in due to entrypoint.sh or an entry in .bashrc.

After entering the container you are in the home directory of a Linux system that contains the standard files and the respy folder.

If you want to exit the container, hit Ctrl + d or type

$ exit

Run Jupyter Notebook in container

You can also start Jupyter inside the container and access it from outside. Type

docker run -p 8888:8888 respy jupyter notebook --no-browser --port=8888 --ip=0.0.0.0

and paste the resulting link into your browser.

Warning

On Windows you have to replace the hash or 127.0.0.1 with localhost.

Reclaiming space on disk

Docker occupies a lot of space on your disk due to saving snapshots of the container, container itself, images, etc.. To reclaim the space, prune unused docker objects. Make sure that you do not accidentally delete valuable information.

$ docker container prune  # Delete unused containers.
$ docker system prune -a  # Delete unused docker objects.

But even if you reclaim disk space with the above commands, Docker seems to reserve more and more space without freeing it. A restart after the pruning solves this.

mybinder.org

We use mybinder.org to provide interactive versions of our documentation and to offer an easy way to explore the package. But, mybinder also recognizes the Dockerfile and integrates it into its build step. Therefore, the Dockerfile includes some more instruction which are necessary for mybinder, but are also best-practices. To debug the current Dockerfile we can rely on repo2docker which builds the docker image on mybinder and runs the notebook.

Install the package with

$ pip install jupyter-repo2docker

Then, walk into the root directory of the repository of respy and hit

repo2docker .

This will build a Docker container and launch Jupyter notebook in the same environment which is available on mybinder.org. Check for memory errors or other problems which do not appear on your machine but on-line.