Introduction

When engineering containerized workflows, a registry is a core piece of infrastructural plumbing. While public registries like Docker Hub or GitHub Container Registry (GHCR) are fine for open-source projects, they quickly fail to meet the rigorous security, auditing, and performance demands of a private enterprise. A basic self-hosted registry (using the vanilla registry:2 image) is simply a blind HTTP blob store—it lacks the access control, security vulnerability scanning, and automation hooks required for production DevOps environments.

This is where Harbor comes in. Harbor is an enterprise-grade, CNCF-graduated open-source container and OCI artifact registry. It provides the security, role-based access control (RBAC), image signature validation, vulnerability scanning, and storage replication that turn a simple registry into a secure private registry. This guide walks through Harbor's architectural features, a production-grade Docker Compose installation, and key administration best practices for security hardening.

Why Harbor? Moving Beyond the Bare Registry

Harbor surrounds the core OCI container distribution backend with an enterprise management layer. It adds several critical operations capabilities:

  • Projects and Multi-Tenancy: Organize images into logical projects with strict Role-Based Access Control (RBAC). A developer can have read-write access to a `frontend` project but zero visibility into a sensitive `finance` database image.
  • Scoped Robot Accounts: Instead of using personal developer credentials in CI/CD pipelines, Harbor allows administrators to generate scoped, short-lived robot accounts. These tokens are limited to specific actions (e.g., pulling from project A and pushing to project B) and can be easily rotated or revoked.
  • Vulnerability Gating (with Trivy): Harbor integrates with the industry-standard Trivy scanner. Every pushed image is automatically analyzed for security vulnerabilities. Administrators can enforce policies that completely block the deployment or pulling of any image that contains high or critical CVEs.
  • Artifact Trust and Signatures: By integrating with Cosign or Notation, Harbor can verify that an image was signed by your CI/CD pipeline's private key. The registry can block any unsigned image from being pulled, preventing supply-chain attacks where an attacker pushes a compromised image.
  • Tag Retention and Garbage Collection: Keep your storage costs controlled. Harbor allows you to define complex retention rules (e.g., "keep only the last 10 builds, unless tagged as a release") and safely execute garbage collection to prune orphaned layers without service disruption.

Harbor Architecture Overview

Harbor is a system composed of several microservices cooperating within a private network:

  • harbor-core: The main API service managing authentication, projects, RBAC, and replication rules.
  • registry: The underlying distribution service that handles actual push/pull blob storage.
  • harbor-jobservice: An asynchronous task runner that manages image replication, vulnerability scanning, and garbage collection.
  • trivy-adapter: The microservice translation layer that passes OCI images to the Trivy scanning engine.
  • nginx: The front-facing reverse proxy that routes UI, API, and Docker CLI traffic to their respective services.

Production Installation using Docker Compose

To deploy Harbor securely in a self-hosted environment, we recommend using the offline installer, which bundles all necessary container images. Below is a production-grade deployment flow.

Step 1: Download the Offline Installer

# Download the latest stable Harbor offline installer
curl -LO https://github.com/goharbor/harbor/releases/download/v2.11.0/harbor-offline-installer-v2.11.0.tgz

# Extract the archive and enter the directory
tar -xzvf harbor-offline-installer-v2.11.0.tgz
cd harbor

Step 2: Configure harbor.yml

Copy the template configuration file and open it for editing. You must configure your public domain, SSL certificates, database passwords, and data storage paths:

cp harbor.yml.tmpl harbor.yml
nano harbor.yml

Ensure the following fields are accurately configured to secure your registry with TLS:

# The IP address or domain name of your registry
hostname: registry.yourdomain.com

# Secure access via HTTPS (recommended for production)
http:
  port: 80
https:
  port: 443
  certificate: /etc/certs/registry.crt
  private_key: /etc/certs/registry.key

# Set strong administrative and database passwords
harbor_admin_password: "YourSuperSecureAdminPassword!"
database:
  password: "YourSecureDBPassword!"

Step 3: Run the Installer

Execute the installation script, enabling the Trivy vulnerability scanner integration to complete the security pipeline:

# Run installation script with Trivy scanner enabled
sudo ./install.sh --with-trivy

Once completed, Harbor will start its container services. Nginx will route incoming HTTPS requests, and you can access the management portal by navigating to https://registry.yourdomain.com in your browser.

Admin Hardening Best Practices

Maintaining a secure registry requires continuous, proactive administration. Implement these key practices to keep your artifacts hardened:

  1. Integrate Enterprise OIDC / LDAP: Disable local database account creation and integrate Harbor with your company's identity provider (such as Keycloak, Okta, or Active Directory) to centralize user management.
  2. Enforce Vulnerability Gating: In your project settings, toggle the option to "Prevent vulnerable images from running." Set the threshold to Block on High or Critical severity. This stops developers or compromised CI runners from executing raw, un-patched images in production.
  3. Automate Garbage Collection: Container images generate massive storage volume. Schedule Harbor's Garbage Collection (GC) to run weekly during off-peak hours with the "Dry Run" toggle disabled and "Prune Untagged Blobs" enabled to clean up orphaned layers.

Conclusion

Harbor is more than a storage bucket for images—it is a security checkpoint and an orchestrator of artifact lifecycle. By deploying Harbor and securing it with RBAC, vulnerability gating, and signed trust, you establish a solid foundation for supply-chain integrity inside your DevOps pipelines.

Estimated Read Time: 6 minutes

Sources & References: