Private Docker Registry on Nexus: Setup & Optimization

Private Docker Registry on Nexus: Setup & Optimization

Your team cannot push images to Docker Hub — rate limits block pushes after 100 pull/hour for anonymous users. Meanwhile, Maven artifacts are already stored in Nexus. The solution: deploy a private Docker Registry on the same Nexus instance. This provides a single point of access control, caching for external registries, and straightforward CI/CD integration. Our engineers with 10+ years of experience have completed 30+ projects configuring Nexus. We offer turnkey configuration, from HTTP connector setup to LDAP integration and automated cache cleanup.

What Is Nexus Repository Manager?

Nexus Repository Manager by Sonatype is a universal artifact repository. It stores not only Docker images but also Maven, npm, PyPI, Helm charts, APT/YUM packages — all in one installation. For organizations with an existing Nexus, adding a Docker registry is a logical step: one infrastructure, one point of access control. If you need only a Docker registry, Harbor offers richer functionality, but Nexus wins in versatility. Based on our data, caching through Nexus reduces pull times by 70% and saves up to $45–65 per month on traffic.

Which Docker Repository Types Does Nexus Support?

Nexus supports three types:

• Hosted — a private registry for your own images. CI/CD pushes here, Kubernetes deploys from here.
• Proxy — a caching proxy for external registries (Docker Hub, ghcr.io, gcr.io). Nexus caches downloaded images locally. On a subsequent pull, the image is served from cache, bypassing rate limits and reducing external traffic.
• Group — combines hosted and proxy repositories into a single endpoint. Developers and CI configure the group repository and transparently access both local images and images from external registries through the cache.

Typical configuration:

• docker-hub-proxy — proxies hub.docker.com
• ghcr-proxy — proxies ghcr.io
• docker-hosted — your own images
• docker-group — combines all three, port 8083

How to Configure an HTTP Connector?

Nexus listens on a single port by default. The Docker registry requires a separate HTTP connector on a dedicated port for each repository. This is a specific requirement of the Docker Registry API — the /v2/ path cannot be prefixed.

In the repository settings: Repository Connectors → HTTP → 8082 for hosted, 8083 for group.

If Nexus is behind a reverse proxy (nginx, traefik), proxy by port or by hostname. Typical nginx configuration:

server {
    listen 443 ssl;
    server_name registry.example.com;
    location / {
        proxy_pass http://nexus:8083;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_buffering off;
        client_max_body_size 0; # no limit for images
    }
}

client_max_body_size 0 is mandatory — without it nginx returns 413 Request Entity Too Large when pushing images larger than 1 GB.

Authentication and LDAP

Nexus supports built-in users, LDAP, and SAML. For corporate environments, integration with Active Directory via LDAP is standard practice.

For CI/CD: create a local user with the nx-docker-push role for the hosted repository. Use it as a secret in your pipeline:

---
# GitLab CI script:
- echo "$NEXUS_PASSWORD" | docker login registry.example.com -u "$NEXUS_USER" --password-stdin
- docker push registry.example.com/myapp:$CI_COMMIT_SHORT_SHA
---

Proxy Caching: What You Need to Know

When configuring a proxy repository for Docker Hub, provide Docker Hub credentials (even for public images) — otherwise the anonymous rate limit of 100 pulls/hour applies. Credentials are stored in the Nexus Secrets Store.

The cache does not have built-in TTL for specific images — Nexus caches on request and stores until explicit deletion. To manage size, set up a Cleanup Policy (Admin → Cleanup Policies): delete proxy components that have not been accessed for more than 30 days.