# How to Use Custom Containers in Gradient Workflows (private)

Workflows automate machine learning tasks, combining GPU instances with an expressive syntax to generate production-ready machine learning pipelines with a few lines of code.

Gradient uses containers to create consistent, reproducible environments for your workloads. Containers define the runtime and dependencies that Gradient uses when running your code.

You can use one of Gradient’s preconfigured containers, a public container image, or your own private image.

## Add a Container Registry

You can store credentials for private container registries in Gradient so they can be reused across your environment.

In the [Gradient console](https://cloud.digitalocean.com), in the top-right corner, click your profile image, select **Team Settings**, and then click the **Containers** tab.

From the **Containers** page, you can add, edit, or delete registry connections.

### Create a Container Registry Connection

To create a registry connection, click **Add Container Registry**, select the registry type, and then type the required credentials for that registry.

After saving, you can reference the registry by name in your configuration file or container spec.

### Configure Container Registry

The following examples show how to connect different container registries to Gradient. Each example outlines the credentials required for that registry and how to reference the registry name in your container configuration.

## DigitalOcean Container Registry

If your image is stored at `registry.digitalocean.com/your-registry-name/image:tag`, type your container registry information like this:

- **Display name:** `My-Example-DO-Registry`
- **Registry name:** `your-registry-name`
- **API token:** Your DigitalOcean API token

Then, reference it in your configuration like this:

```yaml
image: registry.digitalocean.com/your-registry-name/image:tag
containerRegistry: My-Example-DO-Registry
```

## Docker Hub

If your image is at `example-repository/streamlit-app:latest`, type your container registry information like this:

- **Display name:** `My-Example-DockerHub-Repository`
- **Namespace:** `example-repository`
- **Username:** Your Docker Hub username
- **Password:** Your Docker Hub password

Then, reference it in your configuration like this:

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

Learn more about [Docker registries](https://docs.docker.com/get-started/overview/#docker-registries).

## Google Container Registry (GCR)

If your image is at `us-west1-docker.pkg.dev/project-name/repo-name/image:tag`, type your container registry information like this:

- **Display name:** `My-Example-GCR`
- **Region:** `us-west1`
- **Project:** `project-name`
- **JSON Key:** Your service account JSON key

  For reference, see [GCR authentication docs](https://cloud.google.com/container-registry/docs/advanced-authentication#json-key).

Then, reference it in your configuration like this:

```yaml
image: us-west1-docker.pkg.dev/project-name/repo-name/image:tag
containerRegistry: My-Example-GCR
```

## GitHub Container Registry (GHCR)

If your image is at `ghcr.io/example-org/streamlit-app:latest`, type your container registry information like this:

- **Display name:** `My-Example-GHCR`
- **Organization:** `example-org`
- **Email:** GitHub account email
- **Password:** Personal access token

Then, reference it in your configuration like this:

```yaml
image: ghcr.io/example-org/streamlit-app:latest
containerRegistry: My-Example-GHCR
```

## Other (for Azure or generic registries)

If your image is at `example-registry.azurecr.io/streamlit-app:latest`, type your container registry information like this:

- **Display name:** `My-Example-ACR`
- **Registry URL:** `https://example-registry.azurecr.io`
- **Namespace:** `/`
- **Username:** `_json_key`
- **Password:** Azure Service Principal ID

  For reference, see [Azure docs](https://learn.microsoft.com/en-us/azure/container-registry/container-registry-auth-service-principal#create-a-service-principal).

Then, reference it in your configuration like this:

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

### Use Your Container

You can specify a container image directly in your YAML spec to define the environment for each step.

To use a public TensorFlow container, specify a container image like this:

```yaml
image: tensorflow/tensorflow:2.7.0-gpu-jupyter
```

Gradient then automatically pulls and manages this image when your Workflow runs. To learn more, see the [Workflow spec reference](https://docs.digitalocean.com/products/paperspace/workflows/reference/workflow-spec/index.html.md).

## Build a Custom Container

You can build a custom Docker container and push it to a container registry, such as Docker Hub, DigitalOcean Container Registry, or NGC, for use in Gradient. Custom containers let you define the exact runtime, dependencies, and environment needed for your workloads.

**Tip**: You don’t need to build a container from scratch. Many ready-to-use images are available on [Docker Hub](https://hub.docker.com) and [NGC](https://ngc.nvidia.com/catalog/landing). You can use these as a starting point or modify an existing image to suit your requirements.

Before you use a custom container, you need to [create a machine](https://docs.digitalocean.com/products/paperspace/machines/how-to/create/index.html.md) with [Docker CE](https://github.com/docker/docker-ce), [NVIDIA Docker](https://github.com/NVIDIA/nvidia-docker), and NVIDIA drivers installed. These tools ensure your image is compatible with the GPU runtimes and dependencies that Gradient uses when running containers.

If your local environment doesn’t meet these requirements, you can use a [Paperspace Linux-based machine](https://docs.digitalocean.com/products/paperspace/machines/how-to/create/index.html.md) instead.

### Access Your Docker Hub

To access your Docker Hub, run the following command with your Docker Hub credentials like this:

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

### Create a Dockerfile

After accessing your Docker Hub, create a Dockerfile to define your container’s environment, dependencies, and startup commands like this:

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

In this example, the image is a Paperspace-built TensorFlow 2.0 container optimized for GPU workloads.

You can modify the Dockerfile to include any additional dependencies or setup steps your application requires.

### Build the Image

In the same directory as your Dockerfile, build your image with the following command:

```shell
docker build -t test-container .
```

Then, tag your image before pushing it to a registry like this:

```shell
docker tag test-container <docker-username>/test-container:latest
```

### Push the Image

To push the image to your container registry, run the following command:

```shell
docker push <docker-username>/test-container:latest
```

### Reference Your Custom Container

After your container is pushed to a registry, reference it in your configuration file or container spec like this:

```yaml
image: <docker-username>/test-container:latest
containerRegistry: <your-registry-name>
```

Gradient then automatically pulls and runs the container in your environment.

**Note**: Private containers require registry credentials to be stored in Gradient before use.

### Bring Your Custom Container to Workflows

You can use custom containers in Gradient Workflows to control the runtime environment for each step. This lets you include specific frameworks, libraries, or dependencies that your workflow needs.

When defining your Workflow step:

- For **public images**, specify the container path using the `image` key like this:

  ```yaml
  image: paperspace/gradient-sdk
  ```
- For **private images**, specify both the `image` and `containerRegistry` keys to reference your saved registry credentials like this:

  ```yaml
  image: registry.digitalocean.com/example-registry/my-image:latest
  containerRegistry: My-Example-DO-Registry
  ```

The value of `containerRegistry` must match the name of the registry connection you created in the **Create a Registry Connection** section above.

Learn more about structuring and managing Workflow steps in the [Workflows overview](https://docs.digitalocean.com/products/paperspace/workflows/index.html.md).