Compiling your document in a Docker container

Overview

This method allows you to build CSAS documents without having to install and configure R, RStudio, or LaTeX. This also means that you do not have to worry about which versions of things you have since none of it needs be installed on your machine. You only need to have Docker installed. Docker runs a container which is a type of virtual machine that contains everything including the operating system, which is Linux in this case. The container can be run from any machine, regardless of its native operating system. If it works on my machine, it will work on yours.

The following instructions cover installation of Docker and getting the three document templates compiling:

Install Docker and get DockerHub account

You will need to install Docker on a computer which you have administrative control over (not a DFO machine). You can use any operating system you wish, but if using Windows, you must have at least Windows 10:

https://www.docker.com/products/docker-desktop

Get a DockerHub account so you can get access to the csasdown docker image:

https://hub.docker.com/

Docker installs the Linux subsystem (WSL2) on Windows 10 which allows you to run Linux natively inside Windows. If you want to install Linux, go to the Microsoft store and search for Ubuntu and install it. You can run docker commands from the Linux shell as well as the Powershell.

Pull the Docker image

Once Docker is installed and you have a Docker Hub account, open Powershell or a Linux/MAC shell and type:

docker pull cgrandin/csasdown

If it says you need credentials you will have to run the login command and provide your Docker Hub username and password at the prompts first, then try the pull again:

docker login

If you are using Linux on Windows and get an error like this:

/usr/bin/docker-credential-desktop.exe: Invalid argument

This error seems to happen after updating Docker. It seems the update overwrites a file and we have to modify it post-update. Edit your ~/.docker/config.json file so that the credSstore line looks like it does here:

{
  "_credSstore": "desktop",
  "experimental": "enabled"
}

Note there is an underscore in _credSstore and no .exe extension in desktop

Look under Images in the Docker Hub Desktop software if you want to see that it is loaded.

Once you have pulled an image, it will stay on your computer until you delete it, even if you reboot. So this step only needs to be done once, or if the image is updated.

Run the Docker container

Create a new directory wherever you want to put your new techreport, resdoc, or SR and navigate there in Powershell or terminal, and enter this command (you can also go to a directory of a project you had created previously from your own system or using a Docker container):

docker run -d -p 8787:8787 --name=resdoc --mount type=bind,source="$(pwd)",target=/home/rstudio cgrandin/csasdown

Note that the --name argument defines the name of the container and giving it a meaningful name will make it easy to find in your container list later. If omitted, Docker assigns a meaningless unique two-word phrase.

To launch RStudio server, either:

1. Open a new tab in a web browser (tested in Chrome) and type this in the URL bar:

localhost:8787

or 2. Open the Docker App, find the container you just ran, hover over it, and click the web launch button which looks like a square with an arrow pointing diagonally up and to the right out of it.

If there is a login screen asking for Rstudio name and password, use:

username: rstudio
password: qwerty

Build the csasdown document

An Rstudio instance opens in the browser. Create a new document and build as usual:

csasdown::draft("resdoc")
bookdown::render_book("index.Rmd")

You should see the new files appear in your OS file explorer as well as in the RStudio panel.

Note that if you do getwd() it will tell you that you are in home/rstudio. In fact you are actually writing to files in the directory you navigated to before running the docker run command. The reason for this is that /home/rstudio is the container's working directory, and the files you see on your machine are mounted volumes which the container knows about. That is set up in the --mount type=bind,source="$(pwd)" part of the docker/run command.

You can also run the docker run command above in a directory where you already have a project and the files will be linked automatically.

Running multiple containers simultaneously

To do this you must run on a unique port for each instance, and each container instance will run in a new browser tab. For each new instance, change only the first port number:

docker run -d -p 8000:8787 --mount type=bind,source="$(pwd)",target=/home/rstudio cgrandin/csasdown

Then open a new tab in your web browser and type the following in the URL bar:

localhost:8000

Installing packages from GitHub in the container

If you ever want to install packages from GitHub in your RStudio instance like this:

remotes::install_github("group/repo")

and you get a GitHub API error you may need a file called .Renviron in the directory which contains the text:

GITHUB_PAT = <gh_token>

where <gh_token> is a token you created on your GitHub account. There must be a newline after the line in the file.

That's it, you don't need R, RStudio, LaTeX, or anything else installed on your machine to make CSAS documents.