Introduction: The Case for a Private Container Registry

In the era of cloud-native development, Kubernetes and Docker have become the backbone of modern enterprise infrastructure. As organizations scale their microservices, managing container images and Helm charts efficiently becomes a paramount concern. While public registries like Docker Hub or GitHub Packages are excellent for open-source projects, they often fall short for enterprises requiring stringent security, compliance, and localized control.

Relying solely on external registries introduces risks, including bandwidth bottlenecks, unpredictable subscription costs, and potential data leaks. This is where Harbor enters the picture. Harbor is an open-source, trusted cloud-native registry project that stores, signs, and scans content. By hosting your own Harbor instance on a cloud server, you gain complete autonomy over your artifacts, ensuring that your Docker images and Helm charts remain secure, compliant, and rapidly accessible. This comprehensive guide will walk you through setting up your own private registry using Harbor.

Why Choose Harbor for Docker Images and Helm Charts?

Harbor goes far beyond the capabilities of a basic Docker Registry. It is a Graduated project under the Cloud Native Computing Foundation (CNCF), meaning it has reached the highest level of maturity and adoption. Here is why Harbor is the gold standard for private repositories:

Unified Management: Harbor seamlessly handles both container images (Docker, OCI-compliant images) and Kubernetes Helm charts within a single, cohesive user interface.
Role-Based Access Control (RBAC): Users and repositories can be organized into projects. You can enforce granular permissions, ensuring developers only access the specific images they need.
Vulnerability Scanning: Integrating tools like Trivy allows Harbor to automatically scan images for known vulnerabilities upon upload, preventing compromised code from reaching production.
Content Trust and Signing: With Cosign or Notary integration, you can cryptographically sign images, verifying their authenticity before deployment.
Replication and High Availability: Harbor can replicate images across multiple registries and geographical locations, optimizing performance for distributed teams.

Prerequisites and System Requirements

Before initiating the installation on your cloud server (such as AWS, Google Cloud, DigitalOcean, or a local cloud provider), ensure your environment meets the following baseline criteria:

Hardware Recommendations

CPU: 2 Cores minimum (4 Cores recommended for production with scanning enabled).
Memory: 4 GB RAM minimum (8 GB RAM recommended).
Disk Space: 40 GB minimum, though this scales directly with the number and size of your container images and Helm charts.

Software Prerequisites

A clean Linux distribution (Ubuntu 22.04 LTS or 24.04 LTS is highly recommended).
Docker Engine: Version 17.06.0-ce+ or higher.
Docker Compose: Version 1.18.0+ or Compose V2.
A registered domain name (e.g., hub.yourcompany.com) pointing to your cloud server's public IP address.
An SSL/TLS certificate (Let's Encrypt certificates work perfectly).

Step-by-Step Installation of Harbor via Docker Compose

The most reliable and straightforward method to deploy Harbor on a standalone cloud server is using the official offline or online installer powered by Docker Compose. Follow these sequential steps to set up your repository.

Step 1: System Preparation and Software Updates

Connect to your cloud server via SSH and ensure all system packages are fully updated. Run the following commands:

sudo apt-get update && sudo apt-get upgrade -y
sudo apt-get install curl certbot -y

Next, install Docker and the Docker Compose plugin if they are not already present on your system:

sudo apt-get install docker.io docker-compose-plugin -y
sudo systemctl enable --now docker

Step 2: Obtain an SSL/TLS Certificate

Harbor requires HTTPS by default to maintain strict security during image transfer operations. We will use Let's Encrypt to obtain a free, trusted SSL certificate. Replace hub.yourcompany.com with your actual domain name:

sudo certbot certonly --standalone -d hub.yourcompany.com

The certificates will be saved under /etc/letsencrypt/live/[hub.yourcompany.com/](https://hub.yourcompany.com/). Take note of this path, as it will be required during the Harbor configuration phase.

Step 3: Download the Harbor Installer

Navigate to the official Harbor GitHub releases page and download the latest stable offline installer. Downloading the offline package ensures that all necessary container images are bundled together, simplifying the installation process:

wget [https://github.com/goharbor/harbor/releases/download/v2.10.0/harbor-offline-installer-v2.10.0.tgz](https://github.com/goharbor/harbor/releases/download/v2.10.0/harbor-offline-installer-v2.10.0.tgz)
tar -xvf harbor-offline-installer-v2.10.0.tgz
cd harbor

Step 4: Configure the Harbor Configuration File

Harbor provides a template file named harbor.yml.tmpl. Create a copy of this file and name it harbor.yml:

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

Open the configuration file and modify the following essential parameters to match your specific environment:

Important Parameters to Modify:
• hostname: Set this to your domain (e.g., hub.yourcompany.com).
• http: Leave port as 80.
• https: Uncomment this section, set port to 443, and provide the paths to your SSL certificate (certificate) and private key (private_key).
• harbor_admin_password: Set a strong administrative password for the web console.
• database -> password: Change the default database password to secure internal communications.

Step 5: Run the Installer Script

Harbor includes various pre-built sub-components, such as the Trivy vulnerability scanner. To install Harbor with scanning capabilities enabled, execute the preparation script with the --with-trivy flag:

sudo ./install.sh --with-trivy

The script will verify your settings, generate the required Docker Compose files, pull the necessary container layers, and launch the core services. Once completed, you will see a success message indicating that Harbor is running.

Configuring and Utilizing Harbor for Docker Images

With Harbor successfully running, you can access the elegant dashboard by opening your web browser and navigating to [https://hub.yourcompany.com](https://hub.yourcompany.com). Log in using the username admin and the password defined in your harbor.yml configuration.

Creating a New Project

By default, Harbor contains a library project. For business applications, it is highly recommended to create a dedicated project:

Click on New Project in the main dashboard.
Enter a descriptive project name (e.g., enterprise-apps).
Select the Access Level. Leave "Public" unchecked if you want to enforce absolute privacy.
Click OK to finalize project creation.

Pushing Docker Images to Your Private Registry

To interact with your newly deployed registry from your local development machine, you must first authenticate via the command-line interface:

docker login hub.yourcompany.com

Provide your Harbor administrative credentials or robot account tokens. Once authenticated, tag your local container images to match your new repository structure and push them to the cloud:

docker tag my-web-app:latest [hub.yourcompany.com/enterprise-apps/my-web-app:v1.0.0](https://hub.yourcompany.com/enterprise-apps/my-web-app:v1.0.0)
docker push [hub.yourcompany.com/enterprise-apps/my-web-app:v1.0.0](https://hub.yourcompany.com/enterprise-apps/my-web-app:v1.0.0)

Utilizing Harbor as an OCI-Compliant Helm Chart Repository

Historically, Helm charts were managed via specialized tools like ChartMuseum. Modern versions of Harbor leverage OCI (Open Container Initiative) registry standards, allowing Helm charts to be managed identically to container images. This completely eliminates the need for separate tracking mechanisms.

Pushing Helm Charts to Harbor via the Helm CLI

Ensure that you have the Helm binary installed on your local workstation. Authenticate your Helm client with your remote Harbor registry using the following OCI syntax:

helm registry login hub.yourcompany.com

To package and push a local Helm chart, navigate to your chart directory and run these commands:

helm package ./my-chart
helm push my-chart-0.1.0.tgz oci://[hub.yourcompany.com/enterprise-apps](https://hub.yourcompany.com/enterprise-apps)

Your Helm chart is now safely versioned alongside its corresponding Docker images inside the enterprise-apps Harbor project. Kubernetes clusters can now pull these charts directly during deployment sequences.

Best Practices for Securing and Maintaining Harbor

Running an enterprise-grade service means maintaining operational integrity over the long term. Adhere to the following architectural best practices to keep your installation running smoothly:

Implement Robot Accounts: Avoid hardcoding your master administrator password into CI/CD pipelines (such as Jenkins, GitLab CI, or GitHub Actions). Instead, generate short-lived, scope-limited Robot Accounts within Harbor for automated image pushing and pulling.
Automate Vulnerability Scanning: Configure your Harbor project settings to "Scan on Push." This guarantees that every layer uploaded to your cloud infrastructure is checked for exploits before it can be deployed to production.
Set Up Retention Policies: Development pipelines can generate massive amounts of artifacts, leading to disk exhaustion. Define strict Tag Retention Rules (e.g., retain only the 10 most recent images) to automatically prune stale assets.
Schedule Garbage Collection: Deleting an image from the UI does not immediately free up physical storage space on the cloud server. You must periodically run or schedule Garbage Collection tasks via the administration dashboard to completely purge orphaned data blocks.

Conclusion

By establishing your own dedicated Harbor instance on a cloud server, you take a monumental step forward in securing and streamlining your organization's cloud-native architecture. Harbor provides a centralized, robust, and audit-ready framework that bridges the gap between raw Docker images and Kubernetes deployments. By leveraging OCI compliance, integration with automated CI/CD infrastructure, and built-in security tooling, you ensure your enterprise applications remain safe, compliant, and under your absolute control.

Building a Private Docker Registry and Helm Chart Repository: A Complete Harbor Guide on Cloud Servers