Skip to main content

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.

See Docker Hub documentation

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:

  1. Subdomain Connectors

    Using a subdomain corresponding to a docker repository to forward requests to the correct repository.

    See Docker Subdomain Connector

  2. Reverse Proxy Redirects

    Using a reverse proxy in front of Nexus Repository, you may dynamically map docker requests to 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.

    See Reverse Proxy Strategies

  3. Port Connectors

    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

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.

5411130.png

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

See Open Containers Initiative documentation

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.

See Docker Schema documentation

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.