Secure Docker Registries for Repository Manager 3

Repository Manager | Reading time: 8 minutes

In this guide

Overview

Docker is technology allowing you to package, provision, and run executable packages – known as application containers. With Nexus Repository 3, you can manage Docker images that can be deployed as a container.

This guide will give you a background on application containerization. Plus, you’ll demonstrate how to configure a Docker private registry with a secure connection. At the end, you’ll get an opportunity to test push and pull commands that pass through the secure network.

Audience

Developers, Administrators, Operations, and Security Personnel

Prerequisites

In order to meet all outcomes in this guide, you must install Docker Engine on your local machine. If you’re on a macOS or Windows you can install Docker Desktop, and work through the steps below to stand up your environment.

Since you’ll use the Docker client in the demonstration at the end, knowledge of Linux/Unix command line skills is also required.

Desired Outcomes

After reading this guide you’ll learn how to:

  • Understand application containers as Docker is a sought-out solution for application development.
  • Understand security protocol needed to interact with a Nexus Repository as private Docker registry.
  • Configure unique and secure ports for Docker repositories in Nexus Repository.
  • Configure reverse proxy server to ensure security protocol across the Docker environment.
  • Test Docker pull and push commands to download and deploy images to the repository manager.

Why Containerization Matters

Application containers such as Docker speed up software development and ease performance overhead. Docker containers are made up of an entire ecosystem for container management. By design, you can package an application and deliver it to the network host, either on-prem or in the cloud. They’re super portable too. A container has the ability to isolate its own runtime environment, application libraries, and services to a single network. This gives containers the ability to run on any machine, in any location.

Containerization matters to your DevSecOps team because the process of deployment becomes easier and more repeatable. Testing, packaging, and integration can be automated in your SDLC. Containers can take a few seconds to deploy to a host. This helps you scale your personnel and the workload can grow and shrink more quickly for on-demand use cases. Your application lifecycle will ultimately be consistent as containers relieve platform compatibility issues and simplify release management.

Container Security in Nexus Repository

Storing Docker containers securely in Nexus Repository is critical to the overall health of your software supply chain. By default, your Docker repositories come with plain HTTP. So, they’re not encrypted. This increases the risk of the Nexus server becoming prey to man-in-the-middle attacks. To optimize your Docker environment with proper security consider:

  • installing a reverse proxy server to secure incoming requests
  • adding an SSL/TLS certificate to help establish the HTTPS connection
  • configuring all Docker repository types with the unique HTTPS connectors

After installing the repository manager you’ll need to set up a reverse proxy to serve requests from a restricted port. This type of server, such as Nginx, sits in front of the Nexus server, intercepting requests from clients.

Reserve proxies are designed to handle incoming connections, decrypting them, and passing them to the repository manager via plain HTTP. In response the message is sent back to the client by way of a secure HTTPS connection. With the help of SSL configuration, the reverse proxy offloads data that may affect the origin server. So it’s immensely helpful for improved security, performance, and reliability.

The Docker platform doesn’t come with authentication or authorization. So, you need to configure an SSL (or TLS) connection to Nexus Repository either directly or, in this case, through a reverse proxy. The private registry for Docker relies on security protocol to establish encrypted links between the repository manager and client. Creating an SSL certificate is the solution. With the certificate you can secure inbound connections to the repository manager configured with an HTTPS port.

When you configure the Nexus server to use HTTPS you’re required to configure a repository connector. Docker client commands use a hostname (e.g. localhost) and the HTTPS port (e.g. 443) in the repository connector to access the repository. Most repository formats serve content through a path created in Nexus Repository (e.g. <nexus-hostname>/<repository-name>/<path to content>). However, secure Docker repositories require repository connectors to pass information due to the container’s unique namespace (e.g. /docker) and the image associated with the container.

For example, when you pull images from a Docker group (e.g. docker-all) this command works:

docker pull repo.example.com:18079/docker/hello-world

However, this command won’t pass information to the Nexus server:

docker pull localhost:8443/repository/docker-internal/

Since you can’t include the repository name in the Docker client request, use a repository connector to assign a port to the Docker repository which can be used in Docker client commands. This option is available in the repository manager UI.

Configure a Secure Docker Registry

In the steps below, we’ll demonstrate the configuration of Nginx as your reverse proxy. This is a crucial part to setting up your Docker environment in Nexus Repository. You’ll need to do the following:

  • install an instance of Nexus Repository 3
  • configure a virtual machine to run Docker containers
  • create hosted, proxy, and group repositories, each with unique HTTPS ports
  • configure Nginx for SSL/TLS translation
  • create a test certificate to manage encrypted communication over HTTPS

After you install Nexus Repository 3, sign into the repository manager and change your credentials. You can review the steps in this lesson.

Configure a Virtual Machine

Docker relies on a feature called Docker Machine to create and provision your containers. When you connect the docker machine to a VM or cloud instance you create a deployment environment to manage all images and layers running on it. Additionally, running the machine secures port mapping to assist with SSL translation.

To set up your VM:

  1. Install Virtualbox on your local machine.
  2. Run docker-machine create virtualbox to establish the connection to Docker Engine.

Configure Your Repositories

Now, you’re ready to create repositories that serves HTTPS requests. Go the the Administration menu. Then select Repositories from the Repository sub-menu for each type.

NOTE: For this guide, you won’t pull images from the caching proxy. In your normal workflow, we recommend you pull from the repository group which already includes images from the proxy repository.

Hosted Repository

Start by creating a hosted repository to execute docker push commands. Let’s call it docker-internal. To create docker-internal:

  1. Click Create repository and select the docker (hosted) recipe.
  2. Fill out the form with the hosted repository name.
  3. Check the HTTPS box in the Repository Connectors section and assign a port number (e.g. 18082).

Group Repository

Then, create a group repository to receive remote and private images with a unique repository name. Let’s call this one docker-all. To create docker-all:

  1. Click Create repository and select the docker (group) recipe
  2. Enter the group repository name in the Name field
  3. Check the HTTPS box in the Repository Connectors section and assign a port number (e.g. 18075)
  4. Migrate docker-internal and docker-hub to the Members field

Configure Reverse Proxy SSL Termination

NOTE: We recommend that you avoid generating self-signed certificates in a production environment. They’re insecure. Instead, purchase a valid certificate authority (CA) for when deploying images to the public or anywhere else. However, for testing purposes you can review the SSL Certificate Guide to see how encrypted communication works.

Now that you set up your repositories for HTTPS connection, configure your Nginx configuration file (nginx.conf). The reverse proxy virtual host will accept HTTPS requests on the standard port 443 and serve content from the repository manager running on the default non-restricted HTTP port 8081 transparently to end users.

To configure the reverse proxy with SSL do the following:

  1. Open your /etc/hosts file in your terminal: sudo vi /etc/hosts
  2. Add an alias to the file: repo.example.com
  3. Save your changes: Esc, :wq
  4. Locate your nginx.conf file then add ssl_certificate and ssl_certificate_key values to the server block, as shown in this sample configuration file.
  5. Restart the nginx.conf file so your machine recognizes the changes: sudo service nginx restart

When you test docker pull and docker push, the requests will be resolved at the new alias on the reverse proxy.

Fetch and Publish Docker Images

Using the Docker client/terminal log into your local hosted and group repositories via their respective repository connectors. With the server host repo.example.com, the authentication commands will be:

  • docker login repo.example.com:18079, for docker-internal
  • docker login repo.example.com:18075, for docker-all

To test docker pull from the group repository (18075) and push to the private repository (18079):

  1. Fetch the Docker image, downloading it to your machine: docker pull repo.example.com:18075/docker/hello-world.
  2. Run the list command to locate hello-world’s associated image ID: docker images.
  3. Tag the image with the ID simulating a version (oncommit) to which you’ve made changes:docker tag <IMAGE ID> repo.example.com:18075/docker/hello-world:oncommit.
  4. Share the image to the private, hosted registry by pushing it to your private repository: docker push repo.example.com:18079/docker/hello-world:oncommit.
  5. Verify the image is present in the hosted repository UI by search or from the Browse menu.

References and Additional Resources

Sonatype offer additional content to help you automate your Docker private registries inside our Nexus products. On our blog check out:

In our support knowledge base, learn more about Docker in the following articles: