Harbor Private Container Registry on Linux with TLS and Retention
- AuthorBen H.
- Date
- Time21 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 harborStep 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.comStep 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.27Step 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 startProduction 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."
