Introduction: The Imperative of Private Container Registries

In the modern cloud-native ecosystem, containerization has transitioned from a competitive advantage to an industry standard. As organizations scale their infrastructure using Docker and Kubernetes, managing software artifacts securely becomes a critical operational challenge. While public registries or managed cloud solutions offer convenience, they often introduce unpredictable costs, potential data sovereignty issues, and a lack of granular access control.

For enterprise-grade environments demanding absolute security and data ownership, self-hosting your registry is the ultimate solution. This blog post provides an exhaustive, step-by-step guide to deploying Project Harbor on a private Linux Virtual Private Server (VPS). By the end of this guide, you will have a fully functional, highly secure repository for both your Docker images and Helm charts, entirely under your control.

---

What is Project Harbor and Why Choose It?

Harbor is an open-source, Cloud Native Computing Foundation (CNCF) graduated registry project that extends the open-source Docker Distribution by adding the functionalities usually required by an enterprise. Unlike basic registries, Harbor focuses heavily on security, compliance, and management efficiency.

Key Features of Project Harbor:

Multi-tenant Role-Based Access Control (RBAC): Ensure that only authorized users and systems can push or pull specific container images and Helm charts.
Vulnerability Scanning: Integrating open-source scanners like Trivy, Harbor automatically inspects images for known vulnerabilities (CVEs) upon upload.
Image Signing and Content Trust: Utilizing Cosign or Notary, Harbor ensures that the images running in your production environment are authentic and have not been tampered with.
Dual Support for Images and Charts: Harbor acts as a unified repository, seamlessly handling OCI-compliant artifacts, Docker images, and Kubernetes Helm charts side by side.

---

Prerequisites and Environment Setup

Before initiating the installation, ensure your Linux VPS meets the minimum system requirements to run Harbor smoothly in a production-like scenario.

Minimum System Requirements:

CPU: 2 vCPUs (4 vCPUs recommended for active vulnerability scanning).
Memory: 4 GB RAM (8 GB RAM recommended).
Disk Space: 40 GB storage minimum (SSD preferred, scale based on your image retention needs).
OS: Ubuntu 22.04 LTS or Ubuntu 24.04 LTS.

Network and Domain Requirements:

To secure your registry, you must access it over HTTPS. Prepare a registered domain name (e.g., registry.yourcompany.com) and configure its A Record to point to your VPS public IP address.

---

Step 1: Installing Docker and Docker Compose

Harbor is distributed as a multi-container application orchestrated via Docker Compose. Let us prepare the host system by updating packages and installing the required Docker engine components.

sudo apt update && sudo apt upgrade -y
sudo apt install -y curl apt-transport-https ca-certificates gnupg lsb-release

Next, add the official Docker GPG key and repository, then install Docker Ce and the Docker Compose plugin:

sudo mkdir -p /etc/apt/keyrings
curl -fsSL [https://download.docker.com/linux/ubuntu/gpg](https://download.docker.com/linux/ubuntu/gpg) | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] [https://download.docker.com/linux/ubuntu](https://download.docker.com/linux/ubuntu) $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Verify that the services are active and running:

sudo systemctl status docker
docker compose version

---

Step 2: Securing Traffic with Let's Encrypt TLS Certificates

Absolute security requires encrypted transmission. Never expose a private registry to the public internet via unencrypted HTTP connections.

We will use Certbot to provision a free, automated TLS/SSL certificate from Let's Encrypt.

sudo apt install -y certbot
sudo certbot certonly --standalone -d registry.yourcompany.com

Once the challenge completes, your certificates will be securely saved in /etc/letsencrypt/live/[registry.yourcompany.com/](https://registry.yourcompany.com/). Create a dedicated directory to store these certificates for Harbor's internal Nginx reverse proxy:

sudo mkdir -p /data/cert
sudo cp /etc/letsencrypt/live/[registry.yourcompany.com/fullchain.pem](https://registry.yourcompany.com/fullchain.pem) /data/cert/server.crt
sudo cp /etc/letsencrypt/live/[registry.yourcompany.com/privkey.pem](https://registry.yourcompany.com/privkey.pem) /data/cert/server.key

---

Step 3: Downloading and Configuring Project Harbor

Navigate to the official GitHub repository for Harbor and download the latest stable offline installer package.

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 -xvzf harbor-offline-installer-v2.10.0.tgz
cd harbor

Harbor provides a template configuration file. Copy it to create your active configuration profile:

cp harbor.yml.tmpl harbor.yml

Open harbor.yml in a text editor (such as nano or vim) and update the following mandatory parameters to match your infrastructure:

hostname: Set this to your domain, e.g., registry.yourcompany.com.
http: Leave enabled, but ensure port is 80.
https: Enable this section, set the port to 443, and specify the exact paths to your certificates:certificate: /data/cert/server.crt and private_key: /data/cert/server.key.
harbor_admin_password: Choose a highly secure, complex administrative password.
database: Change the default password for the internal PostgreSQL database instance.

---

Step 4: Executing the Installation Script

Harbor allows you to customize components during installation via flags. To enable comprehensive vulnerability scanning capacities, we highly recommend passing the --with-trivy parameter.

sudo ./install.sh --with-trivy

The installer will generate the necessary environment files, load the container images into your local Docker daemon, and launch the multi-container topology using Docker Compose. Upon successful completion, the console will display a success message indicating that Harbor has started successfully.

---

Step 5: Accessing the Web UI and Configuring Core Settings

Open a web browser and navigate to [https://registry.yourcompany.com](https://registry.yourcompany.com). Log in using the username admin and the password defined in your harbor.yml file.

Essential Initial Configuration Tasks:

Create a New Project: Harbor isolates repositories via Projects. Click on "New Project", name it (e.g., production), and set its access level to Private.
Configure Robot Accounts: Avoid using master admin credentials in CI/CD pipelines. Navigate to your project, select Robot Accounts, and generate a token with specific Pull/Push permissions for GitHub Actions, GitLab CI, or Jenkins.
Enable Automatic Scanning: Under the project settings, toggle the option to Automatically scan images on push. This guarantees that no vulnerable layer ever sits uninspected within your registry.

---

Step 6: Pushing and Pulling Docker Images and Helm Charts

To interact with your newly deployed secure registry from your local machine or build servers, perform an explicit login through the command-line interface.

Interacting with Docker Images

docker login registry.yourcompany.com

Tag an existing local image with your custom registry domain and project path, then push it:

docker tag my-app:v1.0 [registry.yourcompany.com/production/my-app:v1.0](https://registry.yourcompany.com/production/my-app:v1.0)
docker push [registry.yourcompany.com/production/my-app:v1.0](https://registry.yourcompany.com/production/my-app:v1.0)

Interacting with Helm Charts

Modern Helm versions treat Helm charts as standard OCI artifacts, allowing them to utilize the identical registry pathing structure as Docker images:

helm registry login registry.yourcompany.com
helm package my-chart/
helm push my-chart-0.1.0.tgz oci://[registry.yourcompany.com/production](https://registry.yourcompany.com/production)

---

Conclusion and Security Best Practices

Congratulations! You have successfully established an independent, enterprise-grade artifact registry using Project Harbor on a Linux VPS. This setup ensures that your proprietary code, intellectual property, and infrastructure deployment files remain fully encrypted, continuously scanned, and safely hosted under your direct management.

As ongoing maintenance, ensure you implement robust automated backup strategies for your persistent data directory (/data), periodically review firewall rules to limit registry access to known office or CI/CD worker IP ranges, and establish a cron job to auto-renew your Let's Encrypt certificates every ninety days.

Self-Hosting a Secure Docker Image and Helm Chart Registry with Project Harbor on Linux VPS