DigitalOcean Container Registry Quickstart

Create a Registry

To create a registry in the control panel:

  1. Visit the registry page.
  2. Enter a name for your registry. This name must:
    • Be unique across all DigitalOcean container registries.
    • Be no more than 63 characters in length.
    • Contain only lowercase letters, numbers, and/or hyphens.
    • Begin with a letter.
    • End with a letter or number.
  3. Select your subscription plan and click Create Registry.

To create a registry using the command-line:

  1. Install doctl and authenticate it with an API token.

  2. Use the registry create command to create your registry:

    doctl registry create <my-registry-name>
    

Push to Your Registry

To push a Docker image to your registry:

  1. Install doctl and authenticate it with an API token.

  2. Use the registry login command to authenticate Docker with your registry:

    doctl registry login
    
  3. Use the docker tag command to tag your image with the fully qualified destination path:

    docker tag <my-image> registry.digitalocean.com/<my-registry>/<my-image>
    
  4. Use the docker push command to upload your image:

    docker push registry.digitalocean.com/<my-registry>/<my-image>
    

    If you push a new image using an existing tag, the tag gets updated but the old image is still accessible by its digest and takes up space in your registry. To reduce your storage usage, you can delete the untagged images and then run garbage collection.

Note

Because image manifests are cached across different regions, pushing an image to an already-existing tag may take up to one hour to update in other regions' caches. To avoid this delay, you can:

  • Use the :latest tag, which is intentionally never cached (as it is usually updated frequently).
  • Use a new, unique tag, such as an incrementing build number or Git SHA hash.
  • Pull specific images by manifest SHA digest, instead of by tag.

Use Images in Your Registry with Kubernetes

To create containers from the images stored in your registry from the control panel:

  1. Visit the registry page and click the Settings tab.
  2. In the DigitalOcean Kubernetes integration section, click Edit to display the available Kubernetes clusters.
  3. Select the clusters and click Save.

The default service account in each of those namespaces is updated to include the secret in its image pull secret.

Use Images in Your Registry with App Platform

  1. Visit the Apps page and either click Create App if starting from scratch, or click an existing app to add your container image to your solution.
    • If adding an image to an existing solution, click the Settings tab. Click the Add Component button and then click Web Service, Worker, or Job.
  2. Select DigitalOcean Container Registry as the source for your code, choose the image you would like to use from the Repository drop-down and select the tag of the image you would like to deploy.
  3. Configure any details such as HTTP routes, environment variables, the run command, or the HTTP port.
  4. On the next page, give your new component a name.
  5. Select the plan and instance size you would like to use when a container is created from the image.

When updating the source image tag, a new deployment will be triggered. If the actual tag name has not changed, it is not guaranteed to pull down a fresh copy of the image due to caching. The recommended approach is to use unique tag names for all image updates.

Manage Images and Tags

To view and delete images in your registry:

  1. Navigate to Container Registry in the control panel.

    If you have a live registry and you have pushed images to it, they will be listed.

  2. Click the plus, +, next to each respository to see its image versions and each version’s tags. You can also see untagged images here, which we recommend deleting through garbage collection.

  3. Choose whether to delete digests or tags:

    • To delete digests, click the menu to the right of an image version and select Delete Digest. Enter your registry name and click Delete to confirm.

      Deleting digests also deletes their associated tags.

    • To delete tags, click the menu to the right of an image version and select Delete Tags. Enter your registry name and click Delete to confirm.

Deleting an image by its tag or manifest does not delete the image layers. We recommend running garbage collection to automatically delete these image layers and all untagged manifests.

Delete Your Registry

To delete your registry using the control panel:

  1. Navigate to Container Registry in the control panel.
  2. Click the Actions drop-down, and select Destroy.

To delete your registry on the command-line, use the registry delete command:

doctl registry delete