Using Docker

Particularly for courses that involve running example code, it's highly recommended that you use a Docker image for development to maintain software version consistency across course developers.

If your course doesn't require any additional packages to run, then you do not need to set up Docker locally but this Docker image: jhudsl/course_template will run and re-render all of your changes as you add them.

If you are new to Docker, you may find it helpful to read this introduction to Docker.

• You will need to sign up with a Docker account if you don't have one.
• If you haven't installed Docker desktop (or need to update it), you can do so here.

If your Docker desktop is running, you should see a Docker whale in your tool bar. On Macs, this will be on the bar on the top of your screen; in Windows, on the bottom right.

A Docker image is similar to a virtual machine - it contains preinstalled software in a preconfigured environment. Docker images can be downloaded from DockerHub, or you can create your own.

We have created the course_template image as a starting point; you can download it from jhudsl/course_template on DockerHub using the docker pull command we have below. To pull the docker image associated with this template, you can run this command below in your command line. This may take a while.

docker pull jhudsl/course_template

This pulls the course_template image from Docker Hub and copies it to your computer. It will be placed in your local collection of Docker images, managed by Docker (not in your pwd).

To use the Docker image associated with the course template, first navigate to the the top of this GitHub repository. Now you can start up the Docker container using the command below.

This runs your local copy of the course_template image (which you downloaded from DockerHub). The option -v $PWD:/home/rstudio mounts pwd (this repo) and makes it available at /home/rstudio within the container. Replace all of <CHOOSE_PASSWORD> (including the < and >) with a password of your choosing.

On a Mac:

docker run -it -v $PWD:/home/rstudio -e PASSWORD=<CHOOSE_PASSWORD> -p 8787:8787 jhudsl/course_template

On a Windows:

docker run -it -v %CD%:/home/rstudio -e PASSWORD=<CHOOSE_PASSWORD> -p 8787:8787 jhudsl/course_template

Do not close this window, but you can minimize it. Open up a new command line window and run the command: docker ps, you should see a container is up and running!

In a web browser navigate to the following to get to an RStudio that is ran from your Docker container.

localhost:8787

To log in, you'll need to use rstudio as the username and whatever password you put for <CHOOSE_PASSWORD> in the above command.

Couple other handy Docker commands:

• To stop your Docker container, run docker ps to obtain the docker container ID. Then you can use that ID to run docker stop <CONTAINER_ID>.
• To remove a docker image (which you may need to do from time to time to clear out space), you can run docker image ls to see all your current images. Then you can run either docker image rm <IMAGE_ID>.
• If you really need to clear out space, you can follow this StackOverflow post on how to remove all images and all containers.

For more info on how to use Docker, they have very extensive documentation here.

Starting a new Docker image

Should you find that your course needs additional packages beyond what's included in the template, you should probably start a new Docker image and you'll need to do two things to get this going:

1. You need to uncomment the Docker image update following these instructions.
2. You'll need to set up a Dockerhub account and set up Dockerhub secrets following these instructions.

To start up a new Docker image for your new course, you can start with the Dockerfile in this repository and add the additional packages you need using the tips in the next section, but you'll need to change the tag (more on that below).

If you wish to keep the Docker image underneath the Dockerhub jhudsl organization account, you'll need to be granted access to that organization -- contact one of the jhudsl team to have them add you.

Adding packages to the Dockerfile

If you find you need a new package to run the code you are adding, you'll need to add the package to the docker/Dockerfile.

Try to keep things in alphabetical order where possible.

Template commands for adding packages to the Dockerfile

For R packages installed from CRAN, you can add to the running vector list of R packages.

To add an R package from Bioconductor, you can follow this kind of format:

RUN Rscript -e "options(warn = 2); BiocManager::install( \
  c('limma', \
    'newpackagename')

To add an R package from GitHub you can add a line that follows this general format (need a comma and space):

RUN Rscript --vanilla install_github.R \
  --packages "jhudsl/didactr, jhudsl/leanbuild, <NEW_PACKAGE>" \

To add a Python package, you will need to add pip3 to install Python packages using this format:

RUN pip3 install \
    "somepackage==0.1.0"

Locally Testing Rebuilding the Docker image

When you've added a package to the Dockerfile, you'll need to check that it builds successfully before including it in a pull request.

First create a GITHUB token file by making a token and copying a pasting it into a plain text file named docker/git_token.txt. (Make sure you do not push this to github and that you delete it after testing your docker image build!)

Then you'll need to rebuild the docker image using this command (first move into the docker directory):

docker build -f Dockerfile . -t jhudsl/course_template

If it fails, often the issue is a missing dependency. Take a look at the error messages and see if you can determine the issue with some Googling. Also be sure that all your directories and files are named correctly.

Once it builds successfully, run the above command with the new name for your docker image make sure that the tag does not have upper case characters):

docker build -f Dockerfile . -t jhudsl/<TAG_FOR_COURSE>

Locally Pushing the Docker image

Next we will need to push the updated image to Dockerhub using (make sure that the tag does not have upper case characters):

docker push jhudsl/<TAG_FOR_COURSE>

Setting up the Docker Build Test Workflow

Next, we will want to update the workflow file called docker_build_test.yml in the .github/workflows/ directory. We need to change the name of the docker image to reflect the image tag we just created.

Thus start a new branch so that you can submit a new pull request with your changes.

Then in the docker_build_test.yml file of the .github/workflows/ directory, search and replace jhudsl/course_template with your docker image tag.

Push the pull request and merge it with the main branch.

Now, when you file a pull request, the Dockerfile build for your docker image will be tested automatically by the GitHub actions.

The Github actions that this repository uses needs four Github secrets set up if you are not a part of the jhudsl organization.

It's important that these are set up and named exactly what they are below in order for Github actions to work correctly.

See Github Actions section for how you can customize Github actions which can change the necessity of these secrets.

To set up these repository secrets, on your repository's main Github page, go to Settings and scroll down to see Secrets on the left side menu bar.

For each new secret, click the New repository secret button and set each as follows, clicking Add secret as you fill each in appropriately:

Name: GH_PAT:
*If you are a part of jhudsl organization you do not need to set these. For value: Create a personal access token following these instructions. Underneath Select scopes, check both repo and workflow. Then copy the PAT and save as the value.

For a course that will need changes to Docker image

If you know for sure that the course you are working on will never require Docker updates -- this may be the case if the course doesn't any interactive code as a part of the material, you can delete the Docker updating chunk or keep it commented out.

However, if you will need to make any change to the Docker image specific to the course you are working on, in the file .github/render-bookdown.yml you should uncomment the ###### START OF DOCKER UPDATE CHUNK up to the part that says ###### END OF DOCKER UPDATE CHUNK.

This will require you to set up the Github secrets for Docker (see next section).

Dockerhub related secrets

Note these are not required if Docker update Github actions are not turned on. *If you are a part of jhudsl organization you do not need to set these.

Name: DOCKERHUB_USERNAME:
For value: put your login username for https://hub.docker.com/

Name: DOCKERHUB_TOKEN:
For value: put an access token for Dockerhub. You can create this by following these instructions.