Accessing previous versions of Terra Jupyter notebook Docker images using the Google Container Registry

Liz Kiernan
  • Updated

You can set up your interactive analysis VM by selecting a pre-configured Terra Docker image. Although these images are routinely updated to include the latest analysis software for your Jupyter Notebook applications, you can still access an old Docker image using these step-by-step instructions. 

Background

Terra maintains multiple Docker images that you can use to set up your Cloud Environment for downstream applications like Jupyter Notebooks. These images include software for R, Python, GATK, Bioconductor, Hail, and more! The Terra Docker images are routinely updated to stay current with the latest software needs. 

But what happens when your notebook analysis requires the software in an older Docker image? 

When this happens, you can still access and use the old images. They are publicly available in the Google Container Registry (GCR), a public repository for Docker container images, and can be uploaded to your Cloud Environment using the Custom Environment option described in this tutorial.

Finding images in the Google Container Registry: Step-by-step instructions

The Broad GCR (called broad-dsp-gcr-public) contains all the public images available at the Broad Institute, including all the Terra images for Jupyter Notebook applications. To find a previous Terra Jupyter Notebook image, follow the steps below:

Step 1. Navigate to the GCR folder for your Docker of interest using the links in the table below.

There are four types of Terra base Jupyter Notebook images (R/Bioconductor, Hail, Default, and Python) available in the Application configuration drop-down menu of the Cloud Environment settings. All Dockers (past and present) for the four image types can be found in the GCR folders listed in the table.  

Terra Image Name GCR Folder (link)
R/Bioconductor terra-jupyter-bioconductor
Hail terra-jupyter-hail
Default (GATK) terra-jupyter-gatk
Python terra-jupyter-python

Step 2. In the GCR folder, use the Docker image version tag to identify your Docker image of interest.

For example, if you need the old Default GATK image (deprecated 4/20/21), find the Docker with the tag 1.0.15 in the terra-jupyter-gatk folder.

If you don't know the Docker version number, see the section, How do I know which image tag (version) I need?, below.

tags.png

Step 3. Select the Docker image of interest using the link in the Name column.

Step 4. On the Digest details page, select the Show Pull Command option.

digest_details.png

Step 5. The top box contains a command for pulling the image by tag. Copy the image name as shown in the box (you'll use this name to set up your Cloud Environment in the next section).

image_name.png

In the example above, you would only copy the image name with the tag, which is us.gcr.io/broad-dsp-gcr-public/terra-jupyter-gatk:1.0.15.

How do I know which image tag (version) I need?

When you first start using any Terra Jupyter Docker image for your notebook analysis, It's a good idea to note the Docker image version tag. You can find the image version tag in the Cloud Environment Settings when you select the image from the Application configuration drop-down (see image below).

mceclip0.png

We also recommend following Terra release notes to stay informed of changes and updates to the default or other Terra base images. If a change was recently made to your choice Docker image, a release note may specify the name of the old image and where to find it.

Uploading previous Terra images to your Cloud Environment: Step-by-step instructions

The Cloud Environment Settings provide the option to use a Custom Environment where you can paste the name of a Docker image. After finding your Docker image of interest and copying the image name in the above section, Finding images in the Google Container Registry, use the following steps to install the image in your Cloud Environment.

  • Step 1. In your Terra workspace, find the Cloud Environment widget in the upper right of the Dashboard and select the gear icon.

    widget.png

    Step 2. Create a custom environment by selecting Customize.

    Customize.png

    Step 3. Select the Custom Environment option from the Application configuration drop-down menu.

    Custom_environment.png

    Step 4. Paste the Terra Docker image you copied from the above section, Finding images in the Google Container Registry (step 5), into the Container image box.

    psate_image.png

    Step 5. At the bottom of the window, select Next. You'll see an unverified Docker warning to inform you that you're using a Custom image. If you're using a previous Terra Jupyter image, you can ignore this warning.

    Step 6. Select Create.
  • Step 1. In your Terra workspace, select the cloud icon (Environment Configuration) in the sidebar.

    environment-configuration-in-sidebar.png

    Step 2. In the Cloud Environment Details pane, select Environment Settings underneath the Jupyter logo.

    environment-settings-in-cloud-environment-details.png

    Step 3. Create a custom environment by selecting Customize.

    Customize.png

    Step 4. Select the Custom Environment option from the Application configuration drop-down menu.

    Custom_environment.png

    Step 5. Paste the Terra Docker image you copied from the above section, Finding images in the Google Container Registry (step 5), into the Container image box.

    psate_image.png

    Step 6. At the bottom of the window, select Next. You'll see an unverified Docker warning to inform you that you're using a Custom image. If you're using a previous Terra Jupyter image, you can ignore this warning.

    Step 6. Select Create.

As soon as you select Create, your Docker image should load quickly (in a couple of seconds). If the Docker image takes a while to load, it might mean you've copied the wrong image name. Make sure you've used the name of the Docker image with the tag appended as shown in Step 5 of the Finding images in the Google Container Registry section. 

Additional resources for exploring Docker images

You can use the following resources to learn more about Docker images, how to explore them, and how to create them.

Additional tips for finding previous Docker images can be found in the article below:

Was this article helpful?

0 out of 0 found this helpful

Have more questions? Submit a request

Comments

0 comments

Please sign in to leave a comment.