Containers

Harbor Private Container Registry on Linux with TLS and Retention

Author :Liam K.
Date :August 3, 2026
Time :21 minutes

Harbor is a CNCF private registry with projects, RBAC, vulnerability scanning, and retention policies. Compared with a bare Docker registry, Harbor gives CI pipelines robot accounts and operators a UI for image lifecycle. This guide installs Harbor with TLS and sets a practical retention baseline.

Prerequisites

Linux server with Docker and Compose (8 GB RAM recommended)
DNS for registry.example.com
TLS certificates from Certbot or an internal CA

Step 1: Download the Harbor Installer

bash

HARBOR_VERSION=v2.12.0
cd /opt
sudo curl -fsSLO https://github.com/goharbor/harbor/releases/download/${HARBOR_VERSION}/harbor-offline-installer-${HARBOR_VERSION}.tgz
sudo tar xzf harbor-offline-installer-${HARBOR_VERSION}.tgz
cd harbor

Step 2: Configure harbor.yml

bash

sudo cp harbor.yml.tmpl harbor.yml
sudo sed -i 's|^hostname:.*|hostname: registry.example.com|' harbor.yml
# Point certificate paths to Let's Encrypt live certs or generate self-signed for lab only:
# sudo certbot certonly --standalone -d registry.example.com
sudo sed -i 's|^  certificate:.*|  certificate: /etc/letsencrypt/live/registry.example.com/fullchain.pem|' harbor.yml
sudo sed -i 's|^  private_key:.*|  private_key: /etc/letsencrypt/live/registry.example.com/privkey.pem|' harbor.yml
# Set harbor_admin_password to a strong value before install.

Step 3: Install and Start Harbor

bash

sudo ./install.sh --with-trivy
sudo docker compose ps
curl -Ik https://registry.example.com

Step 4: Create Project and Robot Account

In the Harbor UI, create a private project such as platform, then create a robot account with push/pull permissions for CI. Prefer robots over personal admin credentials in pipelines.

bash

docker login registry.example.com -u 'robot$platform+ci' -p '<robot-secret>'
docker tag nginx:1.27 registry.example.com/platform/nginx:1.27
docker push registry.example.com/platform/nginx:1.27

Step 5: Retention Policy

bash

# Harbor UI → Project → Policy → Tag Retention
# Example rule: keep last 10 immutable tags matching 'v*' and last 5 'latest-*'
# Also enable Trivy scanning on push for production projects.

Step 6: Backup Harbor Data

bash

cd /opt/harbor
sudo docker compose stop
sudo tar -czf /var/backups/harbor-data-$(date +%F).tar.gz /data/harbor
sudo docker compose start

Production Checklist

Rotate robot secrets and never commit them to Git.
Enable vulnerability scanning and block critical CVEs in promotion workflows.
Keep registry storage on monitored disks with retention enabled early.
Separate projects for staging and production images.
Document restore steps including harbor.yml and /data/harbor.

"A private registry becomes infrastructure only when image promotion, scanning, and retention are policy — not tribal knowledge."

Technical Author

Liam K.

System administrator and technical writer specializing in server infrastructure, security and deployment. Creating comprehensive guides to help you master server administration.