Private Docker Registry with Harbor — manage your company images without lifetime fees

Your team builds Docker images and pushes them to Docker Hub. It works, until someone realizes that public images are public, pull limits kick in, and a third-party central registry doesn't belong to you. If your business runs on containers, the registry is your vault. Renting it from a provider is convenient, but owning it is another story. We, at Meteora Web, chose Harbor for projects that require full control — and in this guide we show you why and how.

Why does a private Docker Registry make sense for your company?

A Docker Registry is the server that stores and distributes your images. Using Docker Hub for free means accepting pull rate limits, public queues, and zero control over retention. In production, a failed pull due to rate limiting is not an inconvenience: it's a blocked deploy. With a private registry, images stay inside your infrastructure, pulls are instant, and costs are predictable. And if you think "we use the free plan," remember: Docker Hub's free plan has pull limits that a CI/CD pipeline can exhaust in a single morning.

The point is not the plan price, it's data ownership. A private registry is like your store's warehouse: you manage it, you protect it, and you don't depend on a provider's opening hours.

What does Harbor do that a simple registry doesn't?

Harbor is an enterprise-grade, open-source registry based on Docker Distribution. It adds security and management: LDAP/OIDC authentication, retention policies, vulnerability scanning with Trivy, multi-cluster replication, and granular roles. In practice, it's the difference between a padlocked locker and a double-key safe with an alarm.

How does company image management work with Harbor?

Harbor organizes images into projects. Each project has its own access, policies, and members. You can have one project for development, one for staging, and one for production, each with different permissions. Images are tagged with clear conventions (e.g., myapp:1.4.2-prod), and retention policies automatically delete old versions. Plus, vulnerability scanning happens at push time, not when someone remembers to do it.

Practical steps to install Harbor with Docker Compose

Harbor is installed with an official installer that generates configuration files. Here are the essential steps:

# 1. Download the installer (version 2.x)
wget https://github.com/goharbor/harbor/releases/download/v2.11.0/harbor-offline-installer-v2.11.0.tgz
tar xzvf harbor-offline-installer-v2.11.0.tgz
cd harbor

# 2. Configure the harbor.yml file
cp harbor.yml.tmpl harbor.yml
# Modify hostname, port, and set HTTPS mode with certificates

# 3. Install with Docker Compose
sudo ./install.sh

After installation, access the web interface at https://your-registry-domain. Create a project, add a user or connect your LDAP, and you're operational.

Configure Docker client for push and pull

To use the registry, the Docker client must trust the certificate. If you use a self-signed certificate, add it to the list of trusted registries on each machine:

# On Linux, create the directory and copy the certificate
sudo mkdir -p /etc/docker/certs.d/registry.example.com
sudo cp ca.crt /etc/docker/certs.d/registry.example.com/
sudo systemctl restart docker

# Login and push
docker login registry.example.com
docker tag myapp:latest registry.example.com/myproject/myapp:1.4.2
docker push registry.example.com/myproject/myapp:1.4.2

From this point, every production deploy uses your registry. No rate limits, no external dependency.

What security strategy should you adopt for the private registry?

Security is not an option, it's the minimum requirement. Harbor gives you the tools, but you must use them well. Here's what works in practice:

• HTTPS mandatory: no plain HTTP, even in the lab. Self-signed certificates must be managed, not ignored.
• Automatic vulnerability scanning: enable scan on push with Trivy. If an image has critical CVEs, the pull in production is blocked.
• Retention policy: keep only the last N versions per project. Old images are attack surface and storage waste.
• Role-based access: developers have push on the dev project, only managers have access to production. The principle of least privilege applies to containers too.

How to enable vulnerability scanning with Trivy

Trivy is integrated into Harbor but must be enabled per project. From the UI, go to the project, select Configuration, and check Automatically scan images on push. For CLI, you can use the harbor command or the REST API:

# Example with curl to trigger a scan
curl -u "admin:password" -X POST https://registry.example.com/api/v2.0/projects/myproject/repositories/myapp/artifacts/1.4.2/scan

With this setup, if an image contains a critical vulnerability, the security team is notified before it reaches production. It's not bureaucracy, it's prevention.

How to integrate the private registry into your CI/CD pipeline?

The private registry is not an island: it must talk to your pipeline. In GitLab CI, GitHub Actions, or Jenkins, the image is built, tagged, and pushed to the registry. Then, at deploy time, it's pulled from the registry. Here's an example with GitHub Actions:

name: Build and Push
on:
  push:
    branches: [main]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Login to Harbor
        run: echo "${{ secrets.HARBOR_PASSWORD }}" | docker login registry.example.com -u "${{ secrets.HARBOR_USERNAME }}" --password-stdin
      - name: Build and push
        run: |
          docker build -t registry.example.com/myproject/myapp:${{ github.sha }} .
          docker push registry.example.com/myproject/myapp:${{ github.sha }}

Be careful with secrets: never hardcode credentials. Use your CI provider's secrets. And set retention to avoid accumulating images from every commit.

Multi-site replication for business continuity

Harbor supports replication between registries. If you have a cluster in one data center and another elsewhere, you can replicate images automatically. So, if one site goes down, the other already has the images ready. It's the same logic as off-site backup, but for containers.

How much does a private Docker Registry cost compared to Docker Hub?

Docker Hub has paid plans starting at a few dollars per month, but the cost isn't just the subscription. With Harbor, you pay for infrastructure you already own: a server with 4 GB of RAM and 50 GB of storage is enough to start. If you already have a CI server, the same can host Harbor. The savings are double: no recurring fees and no pull limits. And if your team grows, Harbor scales without changing providers.

What mistakes to avoid in corporate registry management?

We've seen projects come to us with problems that could have been avoided with minimal planning. Here are the three most common mistakes:

• Leaving the registry without backup: if the server dies, images die too. Configure periodic backups of the database and storage.
• Immutable tags: using latest in production is a disaster. Every deploy must have a unique tag, otherwise you don't know what you're running.
• Ignoring access logs: Harbor tracks every push and pull. If you don't look at logs, you don't know who has access and what they're doing. Check them at least once a month.

In summary

A private Docker Registry with Harbor is not a luxury for big companies. It's the tool that gives you control over your images, the security your clients expect, and the freedom to not depend on an external vendor. If your business runs on containers, the registry is your critical infrastructure. Treat it as such.

What to do now:

1. Install Harbor on a test server with Docker Compose, following the steps above.
2. Configure a project with automatic vulnerability scanning and a retention policy of 10 versions.
3. Move one of your development images from Docker Hub to the new registry and verify push/pull.
4. Integrate registry login into your CI/CD pipeline with provider secrets.
5. Plan registry backup: database and storage, on a daily schedule.

If you want to explore the full journey from prototyping to production, read our pillar on Docker and containerization. And if you're interested in performance optimization, check out our guide on Tailwind animations.