Description of image

How to Manage Paperspace Containers

Paperspace Deployments are containers-as-a-service that allow you to run container images and serve machine learning models using a high-performance, low-latency service with a RESTful API.


Whether you are using Notebooks, Workflows, or Deployments, Gradient uses containers to provide a reproducible code execution environment.

In the case of notebooks, you can either use a preconfigured container or bring your own container. To learn more, see the Notebook Runtimes page.

For Workflows and Deployments, you can either use public containers or private containers to set up your environment. With public containers (for example tensorflow/tensorflow:2.7.0-gpu-jupyter if you wanted to use a generic TensorFlow environment) Gradient takes care of everything once you specify that as the image for your Workflow job. Learn more about Workflow specs on the Workflow specs page.

You can also use a private container in your Workflows and Deployments. Gradient can store and manage your private container registry credentials, which you can learn about below.

Container Registries

You can store credentials for future use in Gradient resources through the Containers tab in your team settings. Access your team settings by clicking on your user image in the top right of the console.

Within the Containers tab you can add new container registries as well as edit or delete your existing registries.

Containers tab

Create a New Container Registry Entry

To create a new container registry connection, choose which container registry you are adding and click Next. This generates an entry form with the information necessary for that specific container registry.

New Container Registry

Container Registry Examples

Here are some examples for each container registry you can create and how it would work. If you do not see the desired container registry below then you can use the Other type.

DigitalOcean Container Registry

This is an example of how to register a DigitalOcean container within Gradient. If the container you are trying to use is located at registry.digitalocean.com/your-registry-name/image:tag then the following would be entered into each field:

  • Display Name: My-Example-DO-Registry
  • Registry Name: your-registry-name
  • API Token: DO API Token

After you have set up your container registry connection, you can reference the container in a deployment spec using:

  • image: registry.digitalocean.com/your-registry-name/image:tag
  • containerRegistry: My-Example-DO-Registry
Docker Hub

This is an example of how to register a Docker Hub container within Gradient. If the container you are trying to use is located in Docker Hub at example-repository/streamlit-app:latest then the following would be entered into each field:

  • Display Name: My-Example-DockerHub-Repository
  • namespace: example-repository
  • username: Username of an authorized Docker Hub account
  • password: Password for Docker Hub account

After you set up your container registry connection, you can reference the container in a deployment spec using:

  • image: example-repository/streamlit-app:latest
  • containerRegistry: My-Example-DockerHub-Repository

Check this out to learn more about docker registries.

Google Container Registry

This is an example of how to register a Google container within Gradient. If the container you are trying to use is located at us-west1-docker.pkg.dev/project-name/repo-name/image:tag then enter the following in each field:

  • Display Name: My-Example-GCR
  • Region: us-west1
  • Project: project-name
  • JSON Key Value: JSON Blob. This JSON key can be created by following these instructions.

After you have set up your container registry connection, you can reference the container in a deployment spec using:

  • image: http://us.gcr.io/example-project/streamlit-app/app-1:latest
  • `containerRegistry``: My-Example-GCR
GitHub Container Registry

This is an example of how to register a GitHub container within Gradient. If the container you are trying to use is located at https://ghcr.io/example-org/image:latest then the following would be entered into each field:

  • Display Name: My-Example-GCHR
  • Organization: example-org
  • Email: Email address for an account belonging to the GitHub organization
  • Password: Access token for the GitHub account

After you have set up your container registry connection, you can reference the container in a deployment spec using:

  • image: https://ghcr.io/example-org/streamlit-app:latest
  • containerRegistry: My-Example-GHCR
Other

This is an example of how to register an Azure container. If the container you are trying to use is located at https://example-registry.azurecr.io/streamlit-app:latest then the following would be entered into each field:

  • Display Name: My-Example-ACR
  • Registry URL: https://example-registry.azurecr.io
  • Namespace: /
  • Username: _json_key
  • Password: Azure Service Principal ID. An Azure Service Principal can be created by following these instructions.

After you have set up your container registry connection, you can reference the container in a deployment spec using:

  • image: https://example-registry.azurecr.io/streamlit-app:latest
  • containerRegistry: My-Example-ACR

Build a Custom Container

This section explains how to create a custom Docker container that you can push to a container registry like Docker Hub, and load that container into Gradient through a notebook, workflow, or deployment.

Tip
Using a custom container does not require building one from scratch. See this article to access many freely available and up-to-date containers hosted on various container registries like Docker Hub, NGC, etc.

Getting Started

You need a computer with DockerCE, NVIDIA-docker, and NVIDIA Drivers installed. If you don’t have an appropriate machine, you can use a Paperspace Linux machine.

From that machine, you need to log into your Docker Hub account using the following command in the terminal:

docker login -u <username> -p <password>

You can make your own Dockerfile from scratch or use another as a template, such as this example. For now, let’s follow this provided sample.

Creating a Dockerfile on Your Machine

First, clone the repo to your machine and navigate to the corresponding directory in your terminal:

git clone https://github.com/gradient-ai/tensorflow-python && cd tensorflow-python

Open the Dockerfile in the IDE of your choice and make edits as necessary. The provided Dockerfile sampled above pulls from Docker Hub a Paperspace-made TensorFlow image designed to run TensorFlow 2.0 on Paperspace GPUs.

Once your Dockerfile is updated, save it, and navigate back to the terminal.

Building the Docker Image

Now that the Dockerfile is created, navigate in your terminal to the same directory your Dockerfile exists and build the image by running:

docker build -t <Name of image> .

Example: docker build test-container

Once you have created the image, you need to tag it so that it can be pushed to your Docker Hub repository. Tag the image using the image id or image name from the image you created, your Docker Hub username, a name for the image, and a tag in the following format:

docker tag <Image ID/Image name> <Docker username>/<Image name>:<Tag>

Example: docker tag test-container paperspace/test-container:latest

Pushing to Docker Hub

Now that we have created and tagged our container, we can push it to Docker Hub and use it within Gradient resources. Use the following docker push command to do so:

docker push <Docker username>/<Image name>:<Tag>

Bring Your Custom Container to Gradient

After you’ve pushed your custom container to Docker Hub, NGC, etc., or you found a public container that is already there, it’s time to pull it into Gradient!

Notebooks

To run your image using Gradient Notebooks, click the Advanced options toggle on the Notebook create page. Follow the rest of the steps here to create your Notebook.

Container Requirements for Gradient Notebooks

To run a custom container using a Gradient Notebook, JupyterLab must be installed on the image. The following are commands you can run in your Dockerfile to ensure the Notebook runs properly.

Dockerfile requirements

  • Install Python: RUN apt-get update && apt-get install -y python3 python3-pip
  • Install JupyterLab: RUN pip install jupyterlab (For more details, see http://jupyter.org/install)

Workflows

Specify the path of the container for example, paperspace/gradient-sdk from within a Workflow step using image. Learn more here.

Deployments

If the image is public, specify the path to the image using the image key. If the image is private, you need to specify the containerRegistry, which you set up in the Create a New Container Registry Entry section of this document.