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.
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)|
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
If you don't know the Docker version number, see the section, How do I know which image tag (version) I need?, below.
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.
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).
In the example above, you would only copy the image name with the tag, which is
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).
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.
Step 2. Create a custom environment by selecting Customize.
Step 3. Select the Custom Environment option from the Application configuration drop-down menu.
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.
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.
Step 2. In the Cloud Environment Details pane, select Environment Settings underneath the Jupyter logo.
Step 3. Create a custom environment by selecting Customize.
Step 4. Select the Custom Environment option from the Application configuration drop-down menu.
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.
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: