Secure Docker Registries for Repository Manager 3

Repository Manager | Reading time: 9 minutes

Is this article helpful?

In this guide

Overview

Docker is a 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.

Video

In addition to this written guide, check out this video demonstrating how to set up a Docker registry against a reverse proxy in Repository Manager 3:

 

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 why application containers such as Docker are 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 HTTP 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.

Reverse 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 connection to Nexus Repository either directly or – as a best practice – 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 (or TLS) certificate is the solution. With an SSL certificate entrusted to the reverse proxy, you can secure inbound connections to the Nexus server with repositories assigned unique HTTP ports.

In other words, configure a repository connector for each Docker repository in the Nexus server. The client sends secure requests to the hostname and the custom port 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 Environment

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:

  • configure a virtual machine to run Docker
  • create a test certificate to handle SSL communication
  • configure SSL to terminate at a reverse proxy server
  • create hosted, proxy, and group repositories, each with unique HTTP ports

NOTE: The steps in this guide were demonstrated on Docker Desktop for MacOS. If using a different OS, some steps may vary.

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 Reverse Proxy SSL Termination

Now set up Nginx server – your reverse proxy. In this section you’ll configure the reverse proxy on SSL port 443 to forward requests to an HTTP connector, on the Nexus server. You’ll customize the reverse proxy configuration file so the Docker client trusts self-signed certificates generated from this SSL guide.

After you produce the certificates, follow these steps then launch the server:

  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. Copy the example.cert and example.key certificates to the local Nginx configuration directory: cp /path/to/{example.cert,example.key} /usr/local/etc/nginx/.
  5. 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.
  6. Reload the changes to the configuration file: sudo nginx -s reload.
  7. Start the reverse proxy server and enter your operating system credentials: sudo nginx.

NOTE: You can reference this gist for a full example of a workable nginx.conf.

Configure Your Repositories

Now, you’re ready to create repositories that translate secure requests. In this demo a caching proxy – docker-hub – was already created. In your normal workflow, we recommend you pull from the repository group which already includes images from the proxy repository.

Go to the Administration menu. Then select Repositories from the Repository sub-menu for each type.

Hosted Repository

Start by creating a hosted repository to receive docker push commands. Let’s call it docker-internal.

  1. Click Create repository and select the docker (hosted) recipe.
  2. Fill out the form with the repository name.
  3. Check the HTTP connector box and add a port number (e.g. 8086).

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.

  1. Click Create repository and select the docker (group) recipe.
  2. Fill out the form with the repository name.
  3. Check the HTTP connector box and add a port number (e.g. 8087).
  4. Migrate docker-internal and docker-hub to the Members field.

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:8086, for docker-internal
  • docker login repo.example.com:8087, for docker-all

To test docker pull from the group repository (8087) and push to the hosted repository (8086):

  1. Fetch the Docker image, downloading it to your machine: docker pull repo.example.com:8087/library/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:8086/library/hello-world:oncommit.
  4. Share the image to the hosted registry by pushing it to your private repository: docker push repo.example.com:8086/library/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 offers 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:

The Sonatype blog hosts several articles on Docker configuration, container security, and image management. Take a moment to learn how you can successfully set it up in your own ecosystem:

Talk to Us

Sign up to receive email alerts each time Sonatype’s Customer Education team publishes new content.

Have more questions or comments? Learn more at my.sonatype.com, and join us in the Sonatype Community.