When your team builds Docker images, they need a place to store them. Docker Hub has rate limits and public defaults, and the plain registry:2 image has no UI, users or scanning. Harbor, a CNCF graduated project, is a full-featured private registry: projects with access control, robot accounts for CI, vulnerability scanning, image signing, replication to and from other registries, and retention policies.

For a minimal private registry, see Docker private registry. Choose Harbor when you need users, scanning and policies.

Requirements

  • A VPS with 2 vCPU, 4 GB RAM minimum (4 vCPU / 8 GB for comfortable use), plus disk for images (often 100 GB+).
  • Docker and Docker Compose. See install Docker.
  • A DNS name, e.g. registry.example.com, and a TLS certificate.

1. Download the installer

Get the latest online installer from Harbor’s GitHub releases:

wget https://github.com/goharbor/harbor/releases/download/v2.12.0/harbor-online-installer-v2.12.0.tgz
tar xzf harbor-online-installer-*.tgz
cd harbor
cp harbor.yml.tmpl harbor.yml

(Use the current version.)

2. Certificates

Obtain a Let’s Encrypt certificate for the hostname, with Certbot standalone or DNS validation, before Harbor takes ports 80/443:

sudo certbot certonly --standalone -d registry.example.com

See Let’s Encrypt.

3. Configure harbor.yml

hostname: registry.example.com

http:
  port: 80
https:
  port: 443
  certificate: /etc/letsencrypt/live/registry.example.com/fullchain.pem
  private_key: /etc/letsencrypt/live/registry.example.com/privkey.pem

harbor_admin_password: <a-strong-initial-password>

database:
  password: <a-strong-db-password>

data_volume: /data/harbor

trivy:
  ignore_unfixed: false
  skip_update: false

4. Install

sudo ./install.sh --with-trivy
docker compose ps        # all Harbor containers should be healthy

Open https://registry.example.com, log in as admin, and change the password immediately.

Certificate renewals: after Certbot renews, rerun ./prepare and docker compose up -d in the Harbor directory (a Certbot deploy hook can do this).

5. Projects, users and robot accounts

  • Projects group repositories, and are public or private.
  • Add users (or connect LDAP/OIDC) with roles per project: Guest, Developer, Maintainer, Project Admin.
  • For CI/CD, create robot accounts with push or pull permissions on specific projects, and use their tokens instead of personal credentials.

6. Push and pull images

docker login registry.example.com
docker tag myapp:1.4.2 registry.example.com/myteam/myapp:1.4.2
docker push registry.example.com/myteam/myapp:1.4.2
docker pull registry.example.com/myteam/myapp:1.4.2

In CI (GitHub Actions, GitLab CI, Gitea Actions), log in with the robot account’s name and token stored as secrets. See Gitea Actions.

7. Vulnerability scanning

With Trivy enabled, Harbor scans images on push (enable Automatically scan images on push per project), and shows CVEs by severity. Project policies can prevent pulling images with critical vulnerabilities, a useful gate before deployment. See patch management.

8. Keep storage under control

Images accumulate quickly:

  • Tag retention rules per project, e.g. keep the last 10 tags per repository, plus anything tagged release-*.
  • Garbage collection (Administration → Clean Up) frees disk space from deleted layers. Schedule it weekly.
  • Monitor /data/harbor disk usage. See disk full troubleshooting.

Replication and proxy cache

  • Proxy cache projects pull through and cache images from Docker Hub, GHCR or Quay. Servers pull from Harbor instead of hitting upstream rate limits. See Docker Hub rate limits.
  • Replication pushes or pulls images between Harbor instances or other registries, for example to keep a copy near servers in another region.

Security and operations

  • Expose only HTTPS (443). Restrict the admin UI to admins via SSO and 2FA, or a VPN.
  • Disable self-registration (Configuration → Authentication).
  • Back up the PostgreSQL database (Harbor’s harbor-db container), harbor.yml, and the data_volume (or rely on replication for image data). See backup strategy.
  • Upgrades: follow Harbor’s upgrade guide. Database migrations run via the prepare and migration tools. Back up first. See updating self-hosted apps.

Harbor vs alternatives

Option Notes
registry:2 Minimal, no UI or users. Fine for single-team private use
Harbor Full features: RBAC, scanning, replication, proxy cache
Gitea / GitLab registries Built into your Git server, simple and convenient
Cloud registries (GHCR, ECR…) Managed, pay per storage and transfer

Quick reference

Task Command / place
Install ./install.sh --with-trivy
Status docker compose ps (in the Harbor directory)
Login docker login registry.example.com
Push docker push registry.example.com/project/image:tag
CI credentials Robot accounts
Free space Administration → Clean Up (GC)

Related: Docker security and Dockerfile tutorial.

  • Docker
  • Self-Hosting
  • DevOps