Being everware compatible

To make your existing repository work with everware it needs to contain a Dockerfile that describes how to create the image your code will run in.

You can think of docker images as extremely lightweight virtual machines. Find out more about docker.

For most users the simplest way to make their repository everware-ready is to create a Dockerfile in their repositories top level directory which simply inherits FROM an existing docker image that works with everware. You can make small modifications to existing images to install extra libraries or pieces of software. If this is you, read about how to use an existing docker image.

If you are an experienced docker user or have really specific needs you can also start from scratch. However this means you need to take care of making the image you create compatible with everware. If this is you, read about how to start from scratch.

Using an existing docker image

A lot of different docker containers already exist, so your chances are good that you do not have to create one from scratch for your repository.

The most basic Dockerfile to get your repository to work with everware is:

FROM everware/base

This is extremely barebones but brings with it all the infrastructure that is needed. Probably you want to extend your image with a few useful bits of software. Check out our everware/container-tools repository and the README.md therein for ideas on how to do that.

You can also use an image which has more software pre-installed. The everware-dimuon-example repository uses a Dockerfile which takes a base image (anaderi/rep-jupyterhub) and extends it by installing two additional python libraries. This is convenient as that docker image already contains a large number of libraries and all the everware specific setup steps.

Check out the anaderi/jupyterhub Dockerfile to see the long list of software installed by default.

If you do not need extra setup steps for your code to run you can use anaderi/rep-jupyterhub as the basis for your repository by creating a Dockerfile in the top level directory of your repository with the following contents:

FROM anaderi/rep-jupyterhub
MAINTAINER John Doe <john.doe@example.com>

This is enough to make your repository everware-ready.

Building your own image from scratch

If you are more experienced with docker or have special requirements then you can start from scratch. However this means you need to make sure your docker image contains a few extra things to make it work with everware. When the container is started it needs to launch a custom singleuser.py script which comes from jupyterhub (this takes care of setting up routing, etc) as well as cloning the git repository.

For details of how to setup a container from the Ubuntu base image check out the everware/container-tools repository and the README.md. The repository contains two images: everware/base and everware/science-python. These are not meant for production use but to document the process of creating your own containers from scratch and then building on top of them.

The everware/container-tools repository contains examples, documentation, and tools for constructing and populating your containers.

The everware/base container does just the bare minimum to be compatible with everware. As a result it does not contain any special libraries. It does install python 2 and 3. Python 3 is required for jupyterhub which is what everware uses as the web-interface.