You can set up your Cloud Environment software 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.
- Part 1: Finding Terra images in the Google Container Registry
- Part 2: Uploading previous Terra images to your Cloud Environment
- Additional resources for exploring Docker images
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.
Part 1: Finding images in the Google Container Registry
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, use the following steps:
- 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 Cloud Environment widget's Application configuration drop-down. 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
- 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 note below.
- Select the Docker image of interest using the link in the Name column
- On the Digest details page, select the Show Pull Command option
- 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 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 widget when you select the image from the Application configuration drop-down (see picture 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.
Part 2: Uploading previous Terra images to your Cloud Environment
Your Cloud Environment widget provides 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 Part 1 (above), use the following steps to install the image in your Cloud Environment.
- In your Terra workspace, find the Cloud Environment widget in the upper right of the Dashboard and select the gear icon
- Create a custom environment by selecting Customize
- Select the Custom Environment option from the Application configuration drop-down menu
- Paste the Terra Docker image you copied from Part 1 (step 5) above into the Container image box
- 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.
- Select Create
As soon as you select Create, your Docker image should load quickly (in a couple of seconds) and your Cloud Environment widget will start up and display the word "Creating".
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 Part 1 step 5.
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: