Install Harbor (artifact registry)

This guide explains how to install and configure Harbor on an Ubuntu 24.04 LTS server. Harbor is a leading cloud-native artifact registry ( CNCF graduated project): it lets you store artifacts in OCI (Open Container Initiative) format. You can host your Docker builds (container images), your Helm charts for Kubernetes, as well as SBOM (Software Bill of Materials) and, in recent versions, AI/ML artifacts. Harbor integrates Trivy for vulnerability scanning, RBAC, OIDC/LDAP, and replication between registries.

The deployment described here uses the official installer (Docker Compose) on a VM or dedicated server, with HTTPS and Let's Encrypt certificates.

Order a Server

To host your Harbor instance, HostMyServers offers several suitable options:

Performance VPS - Ideal for a test registry or small volume
NVMe VPS - Excellent value for money
Eco Dedicated Servers - For many projects or images
Performance Dedicated Servers - Maximum performance

Prerequisites

SSH access as root or user with sudo
Ubuntu 24.04 LTS 64-bit system
Docker (engine 20.10.10+) and Docker Compose (v2 or v1.18+)
A domain name (e.g. harbor.yourdomain.com) with an A record pointing to the server IP
Ports 80 (HTTP, for Certbot or redirect) and 443 (HTTPS) accessible

Required Configuration

Component	Minimum	Recommended
RAM	4 GB	8 GB
CPU	2 cores	4 cores
Storage	40 GB	160 GB
Network	100 Mbps	1 Gbps

HTTPS in production

In production, always configure HTTPS with valid certificates (Let's Encrypt or enterprise PKI). Harbor is gradually deprecating HTTP.

Connect to the Server

Connect via SSH to your server:

ssh user@server_ip_address

System Update

Update packages before starting:

sudo apt update
sudo apt upgrade -y

Install Docker and Docker Compose

Harbor relies on Docker and Docker Compose. If not already installed:

sudo apt install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "${VERSION_CODENAME:-$VERSION}") 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:

docker --version
docker compose version

Obtain TLS Certificates (Let's Encrypt)

Harbor must be configured with a certificate and private key. Obtain them with Certbot before installing Harbor (port 80 must be free):

sudo apt install -y certbot
sudo certbot certonly --standalone -d harbor.yourdomain.com -m your-email@example.com --agree-tos --non-interactive

Files will be in /etc/letsencrypt/live/harbor.yourdomain.com/: fullchain.pem (certificate) and privkey.pem (private key). Note these paths for the next step.

Renewal

Certbot renews certificates automatically. After renewal, restart Harbor containers so they reload certificates: cd /opt/harbor && sudo docker compose down && sudo docker compose up -d.

Download and Extract Harbor

Harbor provides an offline installer (includes images) or online (downloads images on first run). We use the offline installer for reliability.

Check Harbor releases on GitHub for the latest stable version (e.g. v2.14.2). Adjust the URL and filename if needed:

cd /opt
sudo wget https://github.com/goharbor/harbor/releases/download/v2.14.2/harbor-offline-installer-v2.14.2.tgz
sudo tar xzvf harbor-offline-installer-v2.14.2.tgz
cd harbor

Configure Harbor

Copy the configuration template and edit it:

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

Essential parameters to change (replace with your values):

# Hostname or domain (never localhost)
hostname: harbor.yourdomain.com

# HTTPS (required in production)
https:
  port: 443
  certificate: /etc/letsencrypt/live/harbor.yourdomain.com/fullchain.pem
  private_key: /etc/letsencrypt/live/harbor.yourdomain.com/privkey.pem

# Admin password (change immediately)
harbor_admin_password: YourSecurePassword

# Data directory
data_volume: /data/harbor

# Vulnerability scan with Trivy (recommended)
trivy:
  ignore_unfixed: false
  security_check: vuln,config,secret
  skip_update: false
  insecure: false

Parameter	Description
`hostname`	Domain or FQDN used to access Harbor (must match certificate)
`https.certificate` / `private_key`	Paths to certificate and TLS key
`harbor_admin_password`	admin account password (change on first access)
`data_volume`	Harbor data storage directory
`trivy.*`	Trivy scanner options (CVE, config, secrets)

Admin password

The default password in the template is Harbor12345. Replace it with a strong password before first startup.

Launch Installation

Run the install script with the Trivy option to enable vulnerability scanning on images:

sudo ./install.sh --with-trivy

The script checks prerequisites, prepares Docker Compose files, and starts containers. You should see:

✔ ----Harbor has been installed and started successfully.----

Firewall

Open HTTP and HTTPS ports if needed:

sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw reload

Access Harbor

Open a browser and go to: https://harbor.yourdomain.com
Log in with default credentials: admin / password set in harbor_admin_password
Change the admin password immediately: Administration → Users → edit admin account
Create a project (e.g. myproject) to push your images to

Push an Image to Harbor

From a machine with Docker installed that can reach your Harbor:

# Log in to registry
docker login harbor.yourdomain.com
# Enter: admin and password

# Tag an image (replace with your project and image)
docker tag nginx:alpine harbor.yourdomain.com/myproject/nginx:alpine

# Push the image
docker push harbor.yourdomain.com/myproject/nginx:alpine

The image appears in the project in the Harbor interface. If Trivy is enabled, a scan can be run automatically or manually to show vulnerabilities (CVE).

Harbor also supports storing Helm charts (OCI format). After configuring Helm with your Harbor registry, you can push and pull charts with helm push / helm pull from the same project. Thus, a single OCI registry can centralize your Docker images and Helm charts for Kubernetes.

Manage and Stop Harbor

Containers are managed by Docker Compose in /opt/harbor:

cd /opt/harbor

# List containers
sudo docker compose ps

# Stop Harbor
sudo docker compose down

# Restart Harbor
sudo docker compose up -d

Troubleshooting

Harbor page not loading or HTTPS error

Ensure hostname in harbor.yml exactly matches the domain used in the browser and the certificate common name.
Check certificate paths: sudo ls -la /etc/letsencrypt/live/harbor.yourdomain.com/
Check logs: cd /opt/harbor && sudo docker compose logs -f proxy

Containers not starting

Check logs: cd /opt/harbor && sudo docker compose logs
Check disk space: df -h (Harbor and images need space)
Ensure ports 80 and 443 are not in use by another service: ss -tlnp | grep -E ':80|:443'

In development, you can add the registry as insecure in /etc/docker/daemon.json (not recommended in production).
In production, ensure the Let's Encrypt certificate is valid and the Docker client trusts the CA (usually the case with Let's Encrypt).

Order a Server​

Prerequisites​

Required Configuration​

Connect to the Server​

System Update​

Install Docker and Docker Compose​

Obtain TLS Certificates (Let's Encrypt)​

Download and Extract Harbor​

Configure Harbor​

Launch Installation​

Firewall​

Access Harbor​

Push an Image to Harbor​

Manage and Stop Harbor​

Troubleshooting​

Harbor page not loading or HTTPS error​

Containers not starting​

Docker login fails (x509, certificate)​

References​