Docker Registry
Docker containers revolutionize how applications are packaged and deployed with Docker Hub being the primary registry for container images. Nexus Repository supports proxying registries such as Docker Hub while deploying your own private hosted repositories. Group repositories combine multiple repositories into a single endpoint so docker clients may easily to request and publish images.
Docker Base Repository Path
Nexus Repository uses the standard url of /repository/{repository_name}/ as the base repository path when download artifacts from a repository.
Example of the base repository path:
https://nexus.example/repository/docker-public/library/alpine:latest
The Docker client has strict requirements for the path where images are hosted in a registry. Docker clients do not allow a repository path to be included as part of the path to a docker registry as the namespace and image name are embedded in the URLs it uses.
In the example below, the namespace is /library for official docker images and the specific image is /alpine:latest.
docker pull registry-1.docker.io/library/alpine:latest
Nexus Repository manages this Docker client limitation with the following methods:
Path Based Routing (preferred)
Nexus repository supports configuring the repository to allow for path based routing. This method includes the repository name in the image namespace when deploying.
Subdomain Connectors
Using a subdomain corresponding to a docker repository to forward requests to the correct repository.
Reverse Proxy Redirects
Using a reverse proxy in front of Nexus Repository, you may remap docker requests to the base repository path of the docker repositories instead of configuring new port connectors for every repository. The reverse proxy does not require port numbers to be specified and therefore no new connectors on your docker repositories are required.
Port Connectors (legacy)
Using networking port connectors to direct traffic to a specific repository by assigning them port numbers. (limit to only 20 connectors/repositories)
See Port Connectors
Path Based Routing
This configuration enables users to provide a repository name in the URL path when issuing docker client commands. This method avoids the need to expose multiple ports or maintain wildcard TLS certificates when configuring subdomains.
docker pull nexus.example/repository-name/namespace/image:latest
In this example, the pulled image is namespace/image.
This configuration is set when adding or modifying a repository in the repository management view.
Select the checkbox to
Enable path based routingin the repository configuration.
Port Connectors
Port Connectors for Docker repositories use networking ports to direct traffic to the correct repository inside of Nexus Repository. You manually select which port number to use for the repository and Nexus Repository will register the port on its web service to listen for incoming requests to that port. These request are directed to the corresponding repository.
Example request using port connectors:
docker pull https://nexus.example:18079/library/alpine:latest
The repository port connectors are set in the repository configuration for the specific docker repository. The ports cannot be used by another application or repositories and the network must direct traffic from that port to Nexus Repository.
As a best practices, we recommend managing SSL connections using a reverse proxy outside of the Nexus Repository to off load the overhead of managing certificates instead of the server configuration. When managing both HTTP and HTTPS traffic inside of Nexus Repository you will need different port numbers assigned to each. Otherwise, only use the connector that is common for your repository.
For better server performance, limit your configuration to only use 20 port connectors. Each port connector must reserve system resources to monitor the exposed port which cannot be used to serve requests to your clients.
Accessing Repositories
Browse Docker repositories in the user interface and inspect the components and assets and their details as documented in Browsing Repositories and Repository Groups.
When using the docker command line client, the structure for commands is as follows:
docker <command> <nexus-hostname>:<https-repository-port>/<namespace>/<image>:<tag> docker search <nexus-hostname>:<https-repository-port>/<search-term>
command
docker commands such as push or pull
nexus-hostname
IP number or hostname of the repository
https-repository-port
The https port in the repository connector configuration
namespace
the optional namespace of the specific image reflecting the owner, if left out this will silently default to /library and utilize Docker Hub
image
the name of the Docker image
tag
the optional tag of the image, defaulting to latest when omitted
search-term
the search term or name of the image to search for
Supporting OCI Images
The OCI specification versions 1.0.0 and 1.0.1 are supported within Docker repositories. This format support is available as of the 3.71 release.
As part of OCI support the following are some of the changes provided:
Blob upload allows uploads of any arbitrary binary format ("application/octet-stream" content-type) when "Strict Content Type Validation" is enabled
The "Location" header is part of the manifest upload response
Endpoint that allows user to delete tag added: DELETE /v2/{name}/manifests/{tag}
The Docker image "mediaType" property is now optional
Support for Docker Registry API
The Docker client tools interact with a repository via the registry API. It is available in version 1 (V1) and version 2 (V2). The newer V2 will completely replace the old V1 in the future. While Docker Hub and other registries and tools use V2, they will sometimes fall back to V1.
Nexus Repository supports the Docker Registry API V1 and V2. All Docker repository configurations contain a section to configure Docker Registry API Support . If you activate Enable Docker V1 API for a repository, it is enabled to use V1 as a fallback from V2. Without this option, any V1 requests result in errors from the client tool.
Note
Generally V1 support is only needed for repository groups that will be used for command line-based searches, when any client side tools in use require V1 or when a upstream proxy repository requires V1. If you are unsure if your setup uses these or V1, it is recommended to activate V1 support as there should be no harm if it is not needed.
Tips for SSL Certificate Usage
Docker relies on a secure connection using SSL with repositories available to client tools via HTTPS.
See Inbound SSL - Serve Content via HTTPS
Nexus Repository Manager is not configured with HTTPS connectors by default as it requires an SSL certificate to be generated and configured manually.
The requirement of Docker to use HTTPS forces the usage of SSL certificates. By default, Docker looks up the validity of the certificate by checking with certificate authorities. If you purchased a certificate that is registered with these authorities, all functionality works as desired.
If you create a certificate yourself with tools such as openssl, it is self-signed and not registered. Using a self-signed certificate requires further configuration steps to ensure that Docker can explicitly trust it.
Warning
Docker Daemon can stand up instances with the --insecure-registry flag to skip validation of a self-signed certificate. However, Nexus Repository does not support the use of the flag as it is known to cause implementation issues.
To generate a trustworthy self-signed certificate for the repository manager use keytool, a utility that lets you manage your own private key pairs and certificates. See our knowledge base article to learn how to configure the utility.
Docker Manifest Lists
Docker manifest lists allow a manifest to represent support for multiple architectures while maintaining a single image:tag reference format.
Supported Docker Client
The docker client version 1.8 is the minimum version that works with Nexus Repository.
We recommend staying on the latest version when possible.
Docker is a fast-moving project and requires the usage of current operating system versions and tools.
Migrate Between Routing Methods
To migrate from port-based or subdomain routing to path based routing you need to set up new repositories during the transition or do a hard cutover from their current routing to the desired routing. Using a mix of docker repository routing types at the same time is not supported.
We recommend using new group repositories configured with the new routing type containing a similar mix of hosted and proxy repositories so that your build managers may switch to the new type directly.
For example, when exposing the following group repository using port connectors, a new repository group is configured with Path Based Routing containing the same mix of repositories.
- old-docker-group -> port connector: 18079 |- docker-proxy |- focker-hosted > docker pull https://nexus.example:18079/library/alpine:latest ## new repository group - new-docker-group -> path based routing |- docker-proxy |- focker-hosted > docker pull https://nexus.example/new-docker-group/library/alpine:latest