Title

Chapter 8 Modifying a Docker image

8.1 Learning Objectives

Learning Objectives. This chapter will demonstrate how to: Modify an existing Docker image. Store a Docker image on dockerhub. Incorporate Docker image use into a project.

The docker image you are using from the last chapter was pre-made for you, but you will find depending on the needs of your project, that you may need different packages installed. In this chapter we will introduce you to the basics of how to manage your own Docker image.

8.2 Managing images

Images can be on your own computer or on dockerhub. To see your list of images on your computer, you can go to Docker desktop. From here you will want to delete images and containers periodically because they do take up room on your computer.

A reminder of where to find your current local images. Open up Docker desktop. Click on ‘images’ on the left. This shows the images you have available on your computer. If you hover your mouse over one of these images, you will see a Run button appear. Click the Run button to start a container with this image.

To see what images you have on your internet repository, you can log on to dockerhub. Go here to login (or create a username if you have not yet).

The dockerhub login page.

After you sign into dockerhub, click on the Repositories tab, so you can see the list of repositories you have stored online. At this point, you won’t have any if you just created your dockerhub account. To create a new repository, click the ‘Create Repository’ button.

In your dockerhub main page, you can see the list of repositories you have stored online. At this point, you won’t have any if you just created your dockerhub account. To create a new repository, click the ‘Create Repository’ button.

Upon adding the new repository to dockerhub, you will need name it the same as whatever you are calling it locally. You can put a description and name and click create. On the right it shows how you can interact with this from your local command line.

After you’ve created the image repository, you will be brought to the image repository page. It will tell you Last pushed: never. On the right it will tell you the command you will need in order to push the image to dockerhub.

After you've created the image repository, you will be brought to the image repository page. It will tell you Last pushed: never. On the right it will tell you the command you will need in order to push the image to dockerhub.

Go to your local command line and use the command specified on the right side of your repository page. You don’t have to specify a tagname if you don’t want to. If you don’t want to specify a tagname, leave off the :tagname if you like.

Now you will be able to test pulling your image using docker pull <image name> like we did in the previous chapter. You can also click on the Public View button to copy the pull command for your Docker image.

Docker images can be pulled from being stored online but these images are built originally from a Dockerfile.

8.3 Exercise: Build a Docker image

A Dockerfile is a recipe for how to build a docker image. The best way to learn to write Dockerfiles is to start off with one that is already written and modify it for your needs.

You can practice building a docker image by downloading the dockerfiles we have started and changing it slightly.

8.3.1 Download an example Dockerfile

Get the Python Dockerfile

Download the example Dockerfile for Python analyses.

wget https://raw.githubusercontent.com/jhudsl/Adv_Reproducibility_in_Cancer_Informatics/main/resources/python-docker/Dockerfile

If you get a message like command not found that means you will need to install wget.

Altervatively, you can navigate to the Dockerfile’s page on GitHub and use File > Save as but do not add any suffix to the end of the file (no .txt or anything). Just save it as Dockerfile.

Get the R Dockerfile

Download the example Dockerfile for R analyses.

wget https://raw.githubusercontent.com/jhudsl/Adv_Reproducibility_in_Cancer_Informatics/main/resources/r-docker/Dockerfile

If you get a message like command not found that means you will need to install wget.

Altervatively, you can navigate to the Dockerfile’s page on GitHub and use File > Save as but do not add any suffix to the end of the file (no .txt or anything). Just save it as Dockerfile.

8.3.2 Build a Docker image from a Dockerfile

Place this newly downloaded Dockerfile with the rest of your project files.

Build a docker image from this Dockerfile using the command below, but replace image_name with what you would like your modified image to be called.

docker build -f Dockerfile . -t image_name

Navigate back to your Docker desktop and the images window. If your image built successfully, you should see a new image in your list!

8.3.3 Modify a Docker image

If you want add or remove a package from a Docker image, you’ll need to modify the Dockerfile. Using your preferred text editor (or RStudio or Jupyter Lab), open up the Dockerfile.

You will see the first line in the Docker image is a FROM command. This is a command that will take another docker image to start from. - For our R example, we are starting off with an image that already has R and the tidyverse. - For our Python example we are starting off with an image that already has Python and Jupyter Lab.

There are so many Docker images out there, that it might be that someone has already created a docker image with most of the functionality you need for your project.

FROM is one of the main commands that a Dockerfile can take as described by their documentation:

FROM creates a layer from the another Docker image. COPY adds files from your Docker client’s current directory. RUN builds your application with make. CMD specifies what command to run within the container.

8.3.4 Add to the Dockerfile

To get a feel for how these work, let’s add a line to the your example Dockerfile.

Using your preferred text editor (or RStudio or Jupyter Lab), open up the Dockerfile and add this line at the very end of the file. Do not add this line to the start of the file as this will not work. The FROM command needs to come first.

CMD ["echo","Yay! I added to this Docker image"]

Now re-run docker build as you did in the previous section. (Use the command below but replace image_name with whatever your image is called).

docker build -f Dockerfile . -t image_name

If all built successfully, you should see a message like:

=> exporting to image                                                     0.0s
=> => exporting layers                                                    0.0s
=> => writing image sha256:ayuahgfuiseohfauwheufhauwihefuahweufhawfbuibe  0.0s
=> => naming to docker.io/library/image_name

Now to run the image we can use the docker run command we used in the previous chapter (see below) and we should have a message: Yay! I added to this Docker image pop up upon building.

To run your new Python docker image

But replace image_name with whatever you have called your image.

docker run --rm -v $PWD:/home/jovyan/work -e JUPYTER_ENABLE_LAB=yes -p 8787:8787 image_name

To run the R docker image

But replace image_name with whatever you have called your image.

docker run --rm -v $PWD:/home/rstudio -e PASSWORD=password -p 8787:8787 image_name

Stop and remove these containers before moving on. You can do this by going to Docker desktop and clicking on the trash can button next to each container. For images click Clean up to check off the images you’d like to remove and then hit Remove.

8.3.5 Add another package!

Starting off with your example Dockerfile, we will practice adding another package and re-build the docker image with a new package.

Note that spacing is important as well as having a \ at the end of each line if the command is continuing.

8.3.5.1 Adding an R package

To add R packages from CRAN, you can use this kind of format:

RUN Rscript -e  "install.packages( \
    c('BiocManager', \
      'R.utils', \
      'newpackagename'))"

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 a Python package using pip, you will need to add pip3 to install Python packages using this format:

RUN pip3 install \
    "somepackage==0.1.0"

There are so many things you can add to your Docker image. (Picture whatever software and packages you are using on your computer). We can only get you started for the feel of how to build a Dockerfile, and what you put on your Docker image will be up to you.

To figure out how to add something, a good strategy is to look for other Dockerfiles that might have the package you want installed and borrow their RUN command. Then try to re-build your Docker image with that added RUN command and see if it builds successfully.

And lastly, make sure that whatever changes you make to your Dockerfile, that you add it to your GitHub repository by creating a pull request as we did in Chapter 3.

8.3.6 More about Docker next steps

8.3.7 A list of handy Docker commands:

Get info on current containers:

docker ps

How to stop an individual container:

docker container ls
docker stop <containerID>

Get rid of all non-running containers:

docker container prune

Stop all containers:

docker stop $(docker ps -a -q)

Remove all containers:

docker rm -f $(docker ps -a -q)

If you have any feedback on this chapter, please fill out this form, we’d love to hear your feedback!