Deploy and use the Nexus Docker registry in OpenShift


Want to have a better idea of how imagestreams and Docker registries work with OpenShift? Then you might want to try deploying your own Docker registry.

You probably know that OpenShift comes with its own internal registry. But it’s sometimes useful to have your own registry to be able to play around with. You can use it to see how OpenShift interacts with another registry, or simply use it as a way of getting images into your cluster, if you don’t want to expose OpenShift’s internal registry to the outside world.

Deploying Nexus in OpenShift

This article is a walkthrough on deploying an independent Docker image registry in OpenShift, using the free, open source Nexus 3 from Sonatype.

In a future article, I’ll cover how to use images from this registry in your projects in OpenShift, and how this affects the way you consume those images using imagestreams.

Why Nexus? If you’re a Java developer, then you’re probably already familiar with Nexus. In version 3, Nexus got a complete facelift, and now you can use it to store your container images as well. It’s free, it’s open source, and it’s already been containerised by Sonatype. So it’s a good choice to use as a Docker registry.

In this walkthrough I’m going to use the Nexus quickstart template for OpenShift on GitHub, which uses the official Sonatype Nexus image.

Then I’m going to show you the steps you need in order to create a Docker registry in Nexus, and then expose it from OpenShift.

Side note: Hey! Hello! Hi! This guide isn’t intended for setting up an instance of Nexus in production. It’s meant to be just used for learning, or for a demo.

Deploy a Nexus Docker registry in OpenShift - step by step

  1. Fire up your OpenShift cluster

    As I’ve written above, I’m going to use the oc-cluster-wrapper tool. This tool beefs up the oc cluster up command with some extra helpers. I’m going to use it to pull down the latest version of OpenShift Origin. At the time of writing this article, the latest version is 3.6.0.

    I run this command to spin up a cluster called origin36:

    oc-cluster up origin36 --version="v3.6.0"

    Tip: You should probably make sure that Docker has enough resources for this scenario. I recommend you give Docker 8GB memory or more.

  2. Deploy the Nexus container image

    We’ll deploy Nexus using my forked version of the template in the OpenShiftDemos organisation on GitHub. This template uses the official Nexus 3 image (sonatype/nexus3), with some extra configuration to claim a Persistent Volume for Nexus’s data.

    I’ve extended this template by changing some memory parameters and the deployment strategy.

    The template assumes that you already have at least one Persistent Volume (PV) available in your cluster. PVs are buckets where your containers can permanently store application data. We need PVs when we deploy an application that has state like Nexus. Otherwise, if our Nexus container restarted, its configuration would be lost.

    If you’re using oc-cluster-wrapper, then it creates some sample PVs for you automatically :) . If you’re using another cluster, then check the OpenShift docs on how to create and access Persistent Storage in your cluster.

    From the command line, log in using oc login and then run these commands to deploy Nexus in a container in OpenShift. You’ll see that I’m customising the deployment slightly to increase the memory allocation to Nexus:

    oc new-project nexus
    oc create -f
    oc new-app nexus3-persistent

    When Nexus has been successfully deployed, you can get the URL from the OpenShift web console by browsing to ApplicationsRoutes.

    The URL will be something like

    The Nexus URL in OpenShift web console

    Now Nexus is deployed, we need to create our Docker registry.

  3. Create a Docker registry in Nexus

    Go to the Nexus URL, click Sign in and log in with the default username admin and password admin123.

    Log in to Nexus 3

    Click the cog / gear icon to go into Configuration.

    Go to Nexus configuration

    Choose RepositoryRepositories in the left hand menu.

    Click Create Repository then choose docker (hosted).

    Give the repository a name, e.g. docker, and then check the HTTP box and give a port number of 5000.

    Configuring a Docker registry in Nexus

    Then click the Create repository button.

  4. Expose the registry port in OpenShift

    We now have a fully-functioning Docker registry. But in order to be able to access it from outside the OpenShift cluster, we need to create a Route to it. This will allow us to push to the Docker registry from the desktop.

    First, expose port 5000 in the nexus container. This is done by editing the DeploymentConfig. You can either edit the object directly using oc edit, or using the Web Console, or you can use the oc patch command. oc patch allows you to making a change to an object in OpenShift, in a single command.

    In my case, I’m going to use oc patch. I’m going to patch the list of container ports in the DeploymentConfig definition, and add port 5000 to that list. In other words, I’m going to add 5000 as a new exposed port:

    oc patch dc nexus -p '{"spec":{"template":{"spec":{"containers":[{"name":"nexus","ports":[{"containerPort": 5000,"protocol":"TCP","name":"docker"}]}]}}}}'

    This will automatically start a new deployment, so Nexus will take a minute or two to restart.

    Now we’ve exposed that port in the container, we want to add that port to a Service, which we’ll call nexus-registry:

    oc expose dc nexus --name=nexus-registry --port=5000

    Finally, we create a Route so that this new Service is accessible externally. We’ll use edge SSL termination, which means that OpenShift will encrypt traffic. This means that the service will be exposed securely on port 443:

    oc create route edge nexus-registry --service=nexus-registry
  5. Allow OpenShift to pull images from your Docker registry

    When you first create an OpenShift cluster, it’s configured to only allow images from a specific list of registries. This is so that you can control which registries you want to allow images from.

    To allow OpenShift to pull an image from our new registry, we’ll need to specifically add it.

    This step is important, because if we don’t add our new registry to the allowed list, OpenShift will throw an error (“importing images from registry […] is forbidden, only images from …. are allowed”).

    To add our new registry, we need to edit OpenShift’s configuration file, master-config.yaml.

    If you’re using oc-cluster to run your OpenShift cluster, then this file will be located on your host computer, so it’s easily editable. It’s located in $HOME/.oc/profiles/<profile-name>/config/master/master-config.yaml.

    Inside the file, find the section imagePolicyConfig:

    Image policy config in master-config.yaml

    Add a new entry:

    - domainName: '*'
      insecure: true

    Note: you will need to restart your OpenShift master after making this configuration change. If you’re using oc-cluster, just type oc-cluster down and oc-cluster up <cluster-name>.

    Extra note: Why specify port 443? Because this is the port we’re exposing our registry on. The default Docker registry port is usually 5000, so because we’re using a different port, we should explicitly specify it here.

    Now your Docker registry is configured, exposed outside OpenShift and ready for you to push and pull images.

And that’s it for now! In another article I’ll cover how to push images to this registry from your host computer, and pull images and deploy them into your OpenShift cluster.

Leave a Comment