A Docker Registry is treated in Octopus Deploy as a feed that supplies images that are run as containers on a Docker Engine host.
See an example deployment using Docker Registries in our guide: Docker run with networking.
Using Docker registries in Octopus Deploy
In Octopus Deploy, Docker registries are treated very similarly to Package Repositories, and Images are treated very similarly to Packages.
Octopus Deploy supports the Docker Registry Version 1 and Version 2 API specifications as outlined in the Docker reference files. You can access Docker Registries with or without using credentials, depending on registry configuration. You can use one of the hosted public registries, like Docker Hub, or you can host your own Private Registry.
How Octopus Server and deployment targets integrate with Docker Registries
The Docker Registries you configure need to be accessed by both the Octopus Server and your deployment targets.
The Octopus Server will contact your registry to obtain information on available images while designing and maintaining your projects. During deployment the docker pull command will be executed on the deployment targets themselves and they will pull the Images directly from the Docker Registry.
Docker registry API version discovery
When you add your Docker Registry as a feed in Octopus Deploy, Octopus will attempt to detect and connect using the appropriate version based on specifications outlined in the relevant Docker API documentation. If your registry does not support the API correctly, it is possible that the connection will not be able to take place. We advise you to click Save and Test once you have entered the registry details to allow the version detection to take place and confirm that your credentials are correct.
According to the Docker API documentation, the version 1 API should have a /_ping endpoint which will respond with a X-Docker-Registry-Version HTTP header in the response.
Similarly, the version 2 API expects a Docker-Distribution-API-Version HTTP header with a value of registry/2.0. Both of these endpoints are expected to be located at an absolute path of either /v1 or /v2 from the host.
Accessing Docker registries from different security zones It is possible that the URI to the Docker Registry will be different for the Octopus Server and the deployment targets. You can use the Registry Path field when configuring the Docker Registry in Octopus to provide an alternative URI to use on the deployment target.
Working with Docker container images in Octopus
Docker images with the same name are grouped together and referred to (in Docker terminology) as a repository. This is very similar to how Octopus, and other package managers like NuGet, treat Packages with the same Name or ID. When you configure a Docker step in Octopus you choose an Image by its Name, just like you would choose a Package ID for any of the other supported packages.
When you create a release in Octopus, you need to choose the “version” of the Image(s) you want as part of the release. Octopus will load the Tags for the Image(s) and attempt to parse them as an Octopus Version.
Container images are downloaded directly by the Deployment Target or Worker Octopus Deploy does not currently support functionality to push Images from the Octopus Server to the deployment targets in the same way that it does with other supported packages. That being said, the layered architecture of Images allows your deployment targets to retrieve only those pieces that have changed from previous versions that are locally available, which is behavior built in to the Docker Engine.
Private registry
The simplest way to host your own private v2 Docker Registry is to run the run a container from the official registry image!
docker run -d -p 5000:5000 --name registry registry:2
This image supports custom storage locations, certificates for HTTPS and authentication. For more details on setting up the registry checkout the official docs.
Other registry options
There are many other options for private registries such as self hosting through Docker Trusted Registry or Artifactory, or using a cloud provider like Azure, Cloudsmith, AWS or Quay.
We have provided further details on setting up a Octopus Feed to the following Docker Registries:
Known limitations
In the current version of ProGet (version 4.6.7 (Build 2)), their Docker Registry Feed does not expose the full Docker API and is missing the _catalog endpoint which is required to list the available packages for release selection. It has been indicated that this may change in a future release.
Authentication to GitLab container registries using a GitLab deploy token is not supported.
Although a search feature is available in the v1 registry API, as of the time of writing there is no built-in search ability in the v2 specifications. There are ongoing discussions around an open GitHub ticket in the Docker registry Github repository however there is no clear indication if one will be provided due to changes in the philosophy behind the registry responsibilities. The current workaround, and one that Octopus Deploy uses when a v2 Docker registry is provided, is to retrieve the full catalog via the /v2/_catalog endpoint and search for the required image locally.
Troubleshooting Registry Connections
If your Octopus Deploy instance is having problems trying to connect with your Docker Registry when running the Save and Test operation, it may failing due to reasons outside the control of Octopus Deploy.
Try to connect to your registry directly through the browser from the same machine that Octopus is hosted on. Use the feed url you provided and ensure that either /v1 or /v2 is appended to the end of the path depending on what version of the Docker Registry API you are running. If the connection is valid then you should receive a 200 response, possibly receiving a user auth challenge (see API details above under Docker Registry API version discovery). If this does not occur then you may be having issues with your registry or network which you may need to fix before using through Octopus Deploy.
Learn more
- Generate an Octopus guide for Docker Registries and the rest of your CI/CD pipeline.
- Docker blog posts.
- Linux blog posts.
Help us continuously improve
Please let us know if you have any feedback about this page.
Page updated on Tuesday, July 9, 2024