Customize Cloud Shell container images

This page describes how to create and use a custom Docker image as a Cloud Shell environment for tutorials and learning activities.

To create a custom Cloud Shell experience, create a Docker image that functions as a custom Cloud Shell environment with your specified additional packages and custom configurations. Your Docker image must be based on the base Cloud Shell image and hosted in Container Registry.

Create a custom Docker image

To follow step-by-step guidance for this task directly in the Cloud Shell Editor, click Guide me:

Guide me

Create your own custom Docker image by following these instructions:

In a Cloud Shell terminal tab, run the following command to create a boilerplate custom image in a repository hosted by Cloud Source Repositories:
```
cloudshell env create-custom-image NEW_REPO_NAME
```
Note: If you'd like to use an existing repository, you can view a list of your repositories by running gcloud source repos list.

Alternatively, if you'd prefer to manually deploy to Container Registry or use your own automation flow, you can create a new, empty Dockerfile and skip to step 3.
Open your new Dockerfile by following the instructions printed to your command line:
```
cd $HOME/NEW_REPO_NAME && cloudshell edit Dockerfile
```
Add any additional packages you want made available in your Cloud Shell experience below the first line. For example:
```
FROM gcr.io/cloudshell-images/cloudshell:latest
RUN apt-get -y install lsof
```
The first line in your Dockerfile, FROM gcr.io/cloudshell-images/cloudshell:latest, references the base Cloud Shell image and shouldn't be removed.
Build your image locally by running:
```
cloudshell env build-local
```
Test your image locally and verify that your installed packages are present by running:
```
cloudshell env run
```
To exit testing, run:
```
exit
```

Commit your code changes locally:

git commit -a -m "Initial custom environment check-in."

Push your code changes to Cloud Source Repositories:
```
git push origin master
```
Finally, push your custom image to Container Registry:
```
cloudshell env push
```

Update your Open in Cloud Shell link

To use your custom image with Open in Cloud Shell links, you need to make it public first. For steps to make a custom image public, follow the Container Registry access control guide.

After you've set up the right access settings, you can update your Open in Cloud Shell link to specify the cloudshell_git_repo and cloudshell_image parameters. For example, to add an Open in Cloud Shell button, edit the URLs in following example and then add a link similar to the following to your Markdown file:

[![Open in Cloud Shell](https://gstatic.com/cloudssh/images/open-btn.svg)](https://shell.cloud.google.com/cloudshell/editor?cloudshell_git_repo=REPO_URL&cloudshell_image=DOCKER_IMAGE_URL)

Replace the following values:

REPO_URL: URL to the location of your repository
DOCKER_IMAGE_URL: URL to the Docker image

For more information about these and other parameters, see Open in Cloud Shell.

Keeping custom container image up-to-date

Your custom container must be based on the latest public Cloud Shell image to work on Cloud Shell. We recommend that you perform weekly rebuilds to keep the custom image up-to-date.