Deploy an image

type

status

date

slug

summary

Deploying images from registries is now in Early Access. Enable the feature from your user or team settings page to try it out.

Deploying with a Docker image

When you create a web service, private service, background worker, or cronjob, you have the option to deploy an image from a Docker registry.

When building an image, you must ensure that the image is built for the linux/amd64 platform (see limitations below).

When you choose the Deploy an existing image from a registry option, you’re prompted to provide the image path and, if applicable, credentials for accessing the image on a private registry. You can choose to deploy a specific tag or digest of the image.

There are a few different ways you can specify your image path. For example, the following are all valid image paths for the alpine image:

alpine - This will default to the latest tag, to docker.io as the host, and to library as the namespace.

library/alpine - This will default to the latest tag and to docker.io as the host.

docker.io/library/alpine - This will default to the latest tag.

docker.io/library/alpine:latest - This path specifies the host, namespace, image name, and tag.

docker.io/library/alpine@sha256:c0669ef34cdc14332c0f1ab0c2c01acb91d96014b172f1a76f3a39e63d1f0bda - This path specifies the host, namespace, image name, and specific digest.

Once we have validated that the image is accessible using the supplied credential, the Next button will be enabled, allowing you to configure your service.

Using Public Docker Images

A public image is an image hosted in a container registry that does not require an authenticated user to download it. In the Image Path field, enter the name of the public image that you want to deploy. For example, if you want to use the Nginx image, you would enter docker.io/library/nginx. There is no need to enter a credential when deploying a public image.

Using Private Docker Images

A private image is an image hosted in a container registry that requires authentication before the image can be downloaded. Render supports passing authentication for the following registries:

Docker Hub

GitHub Container Registry

GitLab Container Registry

You can add credentials when creating a new service.

Choosing to add a credential will open a form for you to enter the appropriate information. You will need to fill in the following information:

Name - The name you would like to give this token. This is for your information only and is not used in the authentication process

Registry - The registry that this token is for. We currently support Docker Hub, GitHub Container Registry, and GitLab Container Registry

Username - The username of your account on that service

Personal Access Token - The token you are using that has been granted permission to pull the image. See instructions for each provider below on how to obtain a personal access token.

Docker Hub

To obtain an access token for Docker Hub, follow these instructions. Your personal access token will need to have access permissions that allow reading of private images.

GitHub

To obtain a access token for GitHub, follow these instructions. Your personal access token will need to have access permissions that allow reading of the private image you wish to deploy.

GitLab

To obtain a access token for GitLab, follow these instructions. Your personal access token will need to have access permissions that allow reading of the private image you wish to deploy.

Managing credentials

Credentials can also be managed from the settings page under the section Container Registry Credentials. Credentials can saved for your account or for teams you belong to.

From the Container Registry Credentials section, you can

Add additional credentials

Update existing credentials

Delete credentials no longer associated with services. NOTE: if the credential is associated with an active service, it cannot be deleted.

Deploying an image manually

To manually deploy an image, use the Manual Deploy button for that service in the Render Dashboard and choose the Deploy latest reference option.

A new deploy of that image will start and will be subsequently deployed to your service.

Deploying an image via webhook

Render offers a Deploy Hook that can be used to trigger a deployment. By adding a imgURL parameter to the URL of your deploy hook with a value of the URL of the image to be deployed, you can deploy a particular image of your service via your deploy hook.

The value of the imgURL parameter can point to a tag or a digest of the image. Please note, this value must be URL encoded.

For example, to deploy the image with the tag latest, the following Deploy Hook URL can be used:

https://api.render.com/deploy/srv-XXYYZZ?key=AABBCC&imgURL=docker.io%2Flibrary%2Fnginx%3Alatest

To deploy a specific SHA of the image, the following Deploy Hook URL can be used:

https://api.render.com/deploy/srv-XXYYZZ?key=AABBCC&imgURL=docker.io%2Flibrary%2Fnginx%40abc123abc123abc123

The response to a GET or POST to this Deploy Hook URL will return an HTTP 200 OK response if the provided git SHA is valid and a deploy of that image. An HTTP 404 Not Found will be returned if the provided image URL is invalid.