Skip to main content

SSL and Repository Connector Configuration

Docker relies on secure connections using SSL to connect to the repositories. You are therefore required to expose the repository manager to your client tools via HTTPS. This can be configured via an external proxy server, which can also be used to scale your repositories, or directly with the repository manager. Further details can be found in Inbound SSL - Configuring to Serve Content via HTTPS.

Interaction of the docker client with repositories requires specific ports to be used. These can be configured in the repository configuration in the Repository Connectors section. In order for this to work on your network, you need to ensure that the chosen ports are available in your organization and not used by some other application, and that no firewall or other network configuration prevents connectivity.

Note

The docker client does not allow a context as part of the path to a registry, as the namespace and image name are embedded in the URLs it uses. This is why requests to repositories on the repository manager are served on a specific and separate port from the rest of the application instead of how most other repositories serve content via a path i.e. <nexus-hostname>/<repositoryName>/<path to content> .

The recommended minimal configuration requires one port for a Docker repository group used for read access to all repositories and one port for each hosted Docker repository that will receive push events from your users. The Repository Connectors configuration, displayed in Figure: “Repository Connector Configuration", is available in the configuration for proxy and hosted Docker repositories as well as Docker repository groups.

5411130.png

Figure: Repository Connector Configuration

If you have configured the repository manager to use HTTPS directly, you have to configure a HTTPS repository connector. If an external proxy server translates incoming HTTPS requests to HTTP and forwards the request to the repository manager via HTTP you have to configure the respective HTTP port.

Note

A configured context-path for the user interface does not affect the repository connector URLs used by Docker. E.g. if your repository manager instance is configured to be available at http://localhost:8081/nexus instead of the default root context http://localhost:8081/, the URLs for your Docker repositories will still only use the configured port for the repository and omit the context path in the URL. This is a side-effect of the the fact that Docker does not support context paths in the registry API.

Tips for SSL Certificate Usage

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.

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.