Introduction

Docker provides a containerised runtime that enables easy and reproducible deployment of applications to production. Unfortunately, these applications are often developed using the local environment of the developer such that it can be difficult to reproduce the results on another machine. Using Docker as a development environment is possible in principle but plagued by problems in practice. For example,

• mounting a folder from the host in the container can cause permission problems,

• ports need to be manually forwarded to run Jupyter notebook servers,

• or credentials are not available inside the container.

These issues can be addressed directly by modifying the arguments passed to the Docker command line interface (CLI), but the resulting commands can be formidable. Docker Interface allows users to define a Docker command declaratively in a configuration file rather than having to remember to type out all required arguments on the command line. In short, Docker Interface is a translator from a command declaration to a Docker command.

Installing Docker interface

You can install Docker Interface using the following pip command (you need a python3 interpreter).

pip install docker-interface

To check that Docker Interface was installed successfully, run

di --help

Using Docker Interface

Docker Interface will attempt to locate a configuration file di.yml in the current working directory. A basic configuration (as a YAML or JSON file) might look like so.

docker: docker  # The docker command to use, e.g. nvidia-docker
workspace: .    # The workspace path (relative to the directory containing the configuration)

All paths in the configuration are relative to the workspace. The values shown above are default values and you can omit them unless you want to change them.

Docker Interface supports two commands:

• build to build a Docker image,

• and run to execute a command inside a Docker container.

Information that is relevant to a particular command is stored in a corresponding section of the configuration file. For example, you can run the bash shell in the latest ubuntu like so: First, create the following configuration file.

run:
  image: ubuntu

Second, run di run bash from the command line. In contrast to docker run ubuntu bash, the di command will open an interactive shell because it starts the container interactively if it detects that Docker Interface was launched interactively. By default, it will also create an ephemeral container which is deleted as soon as you log out of the shell.

Before delving into the plugin architecture that powers Docker Interface, let us consider a simple example for building your own Docker image. Create a Dockerfile with the following content

FROM python
RUN pip install ipython

and modify your di.yml configuration to read:

build:
  tag: my-ipython

Running di build from the command line will build your image, and di run ipython will run the ipython command inside the container. Unless otherwise specified, Docker Interface uses the image built in the build step to start a new container when you use the run command. Note: the run command also sets the environment variable DOCKER_INTERFACE=true which allows you to dynamically detect when running under the control of di.

A comprehensive list of variables that can be set in the di.yml configuration can be found in the Plugin reference.