Dockernel

Makes it possible to utilize arbitrary docker images as Jupyter kernels.

Installation, prerequisites

You will need Docker (obviously). For detailed instructions on how to install
it, see Get Docker page.

To install Dockernel, use Pip.

pip install dockernel

Make sure that the jupyter installation you wish to use with dockerized
kernels is in the same environment as dockernel. Keep in mind, that kernels
installed with Dockernel in one version may not necessarily work with a
different one.

Usage

_Note for Linux users:

If you run into permission errors with docker or dockernel - either use
sudo, or follow the steps outlined in Manage Docker as a non-root
user
guide._

Creating a Dockernel image

First, create a docker image that will host your kernel. This will require a
proper dockerfile. A full example for IPython kernel can be seen
here.

Most kernels take a path to a “connection file” (also called “control file” by
some kernels) as a CLI argument. This file contains all of the information
necessary to start up a kernel, including TCP ports to use, IP address, etc.

When running your container, Dockernel will supply this file and put it into a
predefined path in the container. This path will be given via an environment
variable visible in the container as $DOCKERNEL_CONNECTION_FILE.

Therefore, in order for the kernel to know the connection settings it should
use, you need to pass the contents of this variable in CMD of the container.
For example, for IPython kernel:

CMD python -m ipykernel_launcher -f $DOCKERNEL_CONNECTION_FILE

Or for the Rust kernel (Evcxr, see the
example Rust
dockerfile):

CMD evcxr_jupyter --control_file $DOCKERNEL_CONNECTION_FILE

To build your image, use docker build. E.g. to build the example mentioned
above:

docker build --tag my_kernel - < example_dockerfile

Installing your image as a Jupyter Kernel

After that, use Dockernel to install the docker image as a Jupyter kernel:

dockernel install my_kernel --name dockerized_kernel

… and you should be ready to go! Fire up jupyter notebook and you should
see dockerized_kernel under “New” menu, or in the “Notebook” section of the
Launcher tab in jupyter lab.

Issues or questions?

Post a new issue in the Dockernell Issue Tracker at
GitHub.