Learn how to set up your Jupyter Cloud Environment virtual machine (VM) software with a preconfigured Terra Docker image. Although these images are updated routinely to the latest software, you can still access an old Docker image following these step-by-step instructions.
Background
Terra maintains multiple Docker images for your Jupyter Cloud Environment. These images include software for R, Python, GATK, Bioconductor, Hail, and more. The Terra Docker images are updated routinely to stay current with the latest software needs.
But what happens when your notebook analysis requires software in an older Docker image?
Never fear! You can still use the old images, which are publicly available in the Google Container Registry (GCR), a public repository for Docker container images. They can be uploaded to your Cloud Environment using the Custom Environment option described below.
How to find images in the Google Container Registry
The Broad GCR (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:
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 |
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 How do I know which image tag (version) I need? below.
3. Select the Docker image of interest using the link in the Name column.
4. On the Digest details page, select the Show Pull Command option.
5. The top box contains a command for pulling the image by tag. Copy the image name as shown in the box (use this name to set up your Cloud Environment in the next section).
In the example (screenshot above), you would copy the image name with the tag 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 start using any Terra Jupyter Docker image for your notebook analysis, note the Docker image version tag. 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 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
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, follow these steps to install the image in your Cloud Environment.
1. In your Terra workspace, select the cloud icon in the sidebar
2. In the Cloud Environment Details pane, select Environment Settings under the Jupyter logo.
3. Create a custom environment by selecting the Customize button (bottom right).
4. Select the Custom Environment option from the Application configuration drop-down menu.
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.
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, ignore this warning.
7. 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.