Harbor

Harbor is a self-hosted OCI container image registry with vulnerability scanning, image signing, replication, and RBAC — basically a private Docker Hub. Its compose file is generated by Harbor's own installer from harbor.yml, so a static compose.yaml in this repo would drift immediately (~10 tightly-coupled services: core, registry, database, redis, jobservice, portal, trivy, nginx, etc). Use the official installer instead of hand-rolling compose. See container-requests.md for the "will not be in the repo" rationale.

Project Repository: https://github.com/goharbor/harbor
Documentation: https://goharbor.io/docs/
Releases (installer download): https://github.com/goharbor/harbor/releases

Tutorial: Installing Harbor

1. Prerequisites

Docker Engine 20.10.10+ and Docker Compose 2.0.0+ on the host
A domain name (or IP) that will be Harbor's registry hostname
A TLS certificate, or be prepared to run without HTTPS on a trusted internal network only (Docker refuses to talk to an insecure registry over plain HTTP unless explicitly configured)

2. Download the offline installer

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

Check the releases page for the current version.

3. Configure `harbor.yml`

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

Key fields to set:

hostname: registry.example.com   # the domain or IP clients will use

http:
  port: 80

https:
  port: 443
  certificate: /your/certificate/path
  private_key: /your/private/key/path

harbor_admin_password: ChangeThisPassword

data_volume: /data/harbor

database:
  password: ChangeThisPassword

If you don't have a certificate yet, comment out the entire https: block and drop https from downstream instructions — but note Docker clients will then need insecure-registries configured to push/pull (see step 6).

4. Run the installer

sudo ./install.sh

This generates docker-compose.yml from harbor.yml and brings the stack up. Optional flags:

sudo ./install.sh --with-trivy    # image vulnerability scanning
sudo ./install.sh --with-chartmuseum   # Helm chart repository (deprecated upstream, skip for new installs)

5. Log in to the UI

Open https://registry.example.com and log in as admin with the password set in harbor_admin_password. Immediately:

Create a new project (e.g. homelab) — set it Private or Public
Create additional users under Administration → Users, or configure LDAP/OIDC

6. Push and pull images

docker login registry.example.com
docker tag myapp:latest registry.example.com/homelab/myapp:latest
docker push registry.example.com/homelab/myapp:latest

# on another machine:
docker pull registry.example.com/homelab/myapp:latest

If running without TLS, add the registry to /etc/docker/daemon.json on every client first:

{
  "insecure-registries": ["registry.example.com:80"]
}

then sudo systemctl restart docker.

7. Use it as a pull-through cache / replication target (optional)

Administration → Registries lets you add Docker Hub (or another registry) as an endpoint, then Administration → Replications to mirror images in on a schedule — useful for caching frequently-pulled base images locally.

8. Day-2 operations

cd /opt/harbor
sudo docker compose down
sudo ./install.sh          # re-run after editing harbor.yml to regenerate and restart

Back up data_volume (default /data/harbor) and the Postgres data inside it before any upgrade. Upgrades are major-version-specific — always read the upgrade guide for your version jump, don't just re-run the new installer over old data blindly.

Gotchas

Trivy's vulnerability database downloads on first scan and needs outbound internet access; air-gapped installs need --with-trivy plus manually seeding the DB.
The installer's generated docker-compose.yml is meant to be managed by install.sh, not edited by hand — re-running the installer after config changes is the supported workflow.
Harbor's own database and redis containers store state locally by default; point harbor.yml at external Postgres/Redis instead if you already run those services elsewhere.

4.4 KiB Raw Blame History