docknitr: Using Docker in Rmarkdown

Getting started

To begin with, you need to install Docker from the official site. After you install it, make sure that it is working properly by running the following in your terminal:

docker run python:3 python -c 'print("Python in Docker")'
#> Unable to find image 'python:3' locally
#> 3: Pulling from library/python
#> Digest: sha256:ce94b081f1ffebee1121e507173f12d9d95dff3ffdd979b92b91239198330de5
#> Status: Downloaded newer image for python:3
#> Python in Docker

The output you see shows Docker downloading a pre-made copy of Python 3 (regardless of which operating system you are on and which version of Python you already have installed outside of Docker) and then running some Python code in it to print “Python in Docker”.

If you repeat the same command for a second time, Docker will use the already-downloaded Python and just run your code:

docker run python:3 python -c 'print("Python in Docker")'
#> Python in Docker

Docker’s name for a packaged software environment is Docker image. For example, the thing that got downloaded above when you ran Python in Docker was the Python 3 image. Images have tags of the form of software:version — for example, python:3 is the tag that we used above to tell Docker to download Python version 3.

All the images are isolated from each other — for example, Python version or Python packages available in one image have no bearing on those installed in another image.

Running a docker image creates new session called a Docker container. Just as you can have multiple RStudio sessions running at the same time on your computer, you can run multiple Docker containers at the same time (from the same Docker image, or from different images).

All the containers are also isolated from each other — for example, files created by one container are (by default) not visible to other containers.

In other words, you can think of a docker image as a pre-built collection of software, and a docker container as an isolated session in which you run that collection of software.

Using docker with Rmarkdown

The actual thing we are interested in here is using Docker inside Rmarkdown. To do this, you first have to load the docknitr package:

library(docknitr)

Doing this enables docker as an option inside Rmarkdown. Let’s run some Python code in Rmarkdown using docker:

```{r engine="docker", image="python:3"}
import sys
print("Python in Docker in Rmarkdown, version %s" % sys.version)
```

#> Python in Docker in Rmarkdown, version 3.8.1 (default, Jan  3 2020, 22:44:00) 
#> [GCC 8.3.0]

What if we want to use Python v2 instead? Easy:

```{r engine="docker", image="python:2"}
import sys
print("Python in Docker in Rmarkdown, version %s" % sys.version)
```

#> Python in Docker in Rmarkdown, version 2.7.17 (default, Dec 28 2019, 07:48:40) 
#> [GCC 8.3.0]

If you’ve ever tried to install multiple versions of Python on one computer, you can appreciate how unexpectedly simple this was. (If you haven’t, lucky you.)

File sharing

Normally, Docker containers are isolated from each other and from the rest of your computer. As a result, they don’t have access to files on your computer. For example, this is the list of files seen by Python in Docker:

```{r engine="docker", image="python:3"}
import os
print(os.listdir())
```

#> ['lib', 'media', 'home', 'sbin', 'sys', 'var', 'root', 'run', 'boot', 'etc', 'opt', 'tmp', 'proc', 'srv', 'usr', 'bin', 'dev', 'lib64', 'mnt', '.dockerenv']

These files aren’t anywhere (obvious) on your computer — they are inside the Python 3 Docker image.

If you want your Rmarkdown Docker blocks to see the normal files on your computer, use the share.files=TRUE block option to share your RStudio working directory with the Docker image. (On Windows, you first have to share your drives with Docker in Docker settings.) For example:

```{r engine="docker", image="python:3", share.files=TRUE}
import os
print(os.listdir())
```

#> ['pyseer-tutorial']

That list of files is what’s on my computer; yours would probably be different.

Docker image commands

Whereas some Docker images (such as python) contain a single piece of software, some others contain multiple tools, and therefore require you to specify which you want to run. This is common for images that contain an entire operating system (such as the ubuntu image for Ubuntu Linux), or images that contain a suite of related tools. For example, if you want to have access to all the tools built into Ubuntu, you would want to use the ubuntu image; if you want to run a particular Rmarkdown block through bash (which is one of the tools included in Ubuntu), you can use the command block option:

```{r engine="docker", image="ubuntu:latest", command="bash"}
uname -a
```

#> Linux aa3c7748fbd1 4.4.0-169-generic #198-Ubuntu SMP Tue Nov 12 10:38:00 UTC 2019 x86_64 x86_64 x86_64 GNU/Linux

Let’s take a moment to pause here and appreciate what just happened there: your computer — regardless of what operating system is installed on it — downloaded a copy of Ubuntu Linux, started it inside an isolated session, fed a chunk of your Rmarkdown file into a Linux command inside that session, and fed the output of that command into your Rmarkdown file.

Shorthands

You will probably find yourself frequently using the same Docker images and commands over and over again. For example, you may have multiple Rmarkdown blocks that you want to run in Python, without having to repeat the Python Docker options every time.

To accomplish this, use docknitr::docker_alias. For example, run this to configure python_docker as shorthand for docker engine='docker', image="python:3", share.files=TRUE:

docknitr::docker_alias("python_docker", image="python:3", share.files=TRUE)

Your shorthand has to be recognizable by knitr; by default, this means that it must can’t contain anything other than letters, numbers, and underscores.

Now you can use python_docker as its own Rmarkdown chunk type:

```{python_docker}
import os
print(os.listdir())
```

import os
print(os.listdir())
#> ['pyseer-tutorial']

That covers the basics of getting up-and-running with Docker in Rmarkdown. This much will be useful to you if you want to run code through existing software environments, such as the plain install of Python 3. The next level of Docker power is making your custom software environments. When you are ready for that, check out the custom images vignette.