Harbor mit Docker installieren: CNCF-zertifizierte Container-Registry mit Trivy-Scanning und RBAC

Eine private Registry macht Sie unabhängig von Docker Hub und Cloud-Anbietern. Harbor (CNCF Graduated Project) ergänzt die Image-Ablage um Schwachstellen-Scans mit Trivy, rollenbasierte Zugriffskontrolle (RBAC), Image-Signierung mit Cosign oder Notation, unveränderliche Tags und Replikation zu anderen Registries. Diese Anleitung installiert Harbor v2.15.2 mit dem offiziellen Installer per Docker Compose auf einem Linux-Host.

Voraussetzungen

1. Linux-Host oder VM (Ubuntu 22.04/24.04 oder RHEL/Rocky empfohlen) mit fester IP-Adresse oder DNS-Eintrag; localhost ist als Hostname nicht nutzbar.
2. Docker Engine 20.10+ und Docker Compose Plugin v2.3+ (docker compose), siehe Docker und Docker Compose auf Linux installieren.
3. Mindestressourcen: 2 CPU-Kerne, 4 GB RAM, 40 GB freier Disk-Speicher; Produktionsempfehlung: 4 CPU, 8 GB RAM, 160 GB Disk.
4. OpenSSL für Zertifikate, wget und cosign für Download und Signaturprüfung.
5. Optional für Produktion: TLS-Zertifikat (Let's Encrypt oder selbst-signiert); einen vorgeschalteten Reverse-Proxy beschreibt Traefik als Docker-Reverse-Proxy einrichten.
6. Internetzugang: Der Online-Installer zieht die Images von Docker Hub.

Harbor-Eckdaten im Überblick

Schritt 1: Installer herunterladen und Signatur prüfen

Laden Sie den Online-Installer v2.15.2 herunter und prüfen Sie die Signatur. Die Releases enthalten statt einer .asc-Datei ein Sigstore-Bundle, das Sie mit cosign prüfen:

# Installer und Sigstore-Bundle herunterladen
wget https://github.com/goharbor/harbor/releases/download/v2.15.2/harbor-online-installer-v2.15.2.tgz
wget https://github.com/goharbor/harbor/releases/download/v2.15.2/harbor-online-installer-v2.15.2.tgz.sigstore.json

# Signatur prüfen
cosign verify-blob \
  --bundle harbor-online-installer-v2.15.2.tgz.sigstore.json \
  --certificate-identity https://github.com/goharbor/harbor/.github/workflows/publish_release.yml@refs/tags/v2.15.2 \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  harbor-online-installer-v2.15.2.tgz

# Archiv entpacken
tar xzvf harbor-online-installer-v2.15.2.tgz
cd harbor

Verifizieren: cosign meldet Verified OK. ls im Verzeichnis harbor/ zeigt common.sh, harbor.yml.tmpl, install.sh, LICENSE und prepare.

Schritt 2: harbor.yml konfigurieren

Alle Parameter (Hostname, Passwörter, HTTPS, Trivy) stehen in harbor.yml. Das Skript prepare überträgt sie in die Konfiguration der Container.

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

Die folgende Minimalkonfiguration eignet sich für Test und Entwicklung (nur HTTP). Für den Produktivbetrieb aktivieren Sie HTTPS (Schritt 6).

# harbor.yml – Minimalkonfiguration (HTTP, Test/Entwicklung)
# WICHTIG: 192.168.1.100 durch Ihre IP oder Ihren FQDN ersetzen.
# localhost/127.0.0.1/0.0.0.0 funktionieren NICHT.

hostname: 192.168.1.100

http:
  port: 80

# Für Produktion: HTTPS aktivieren und Zertifikate hinterlegen
# https:
#   port: 443
#   certificate: /data/cert/yourdomain.crt
#   private_key: /data/cert/yourdomain.key

harbor_admin_password: MeinSicheresPasswort123!

database:
  password: MeinDBPasswort456!
  max_idle_conns: 100
  max_open_conns: 900

data_volume: /data

trivy:
  ignore_unfixed: false
  skip_update: false
  # github_token: IHR_GITHUB_TOKEN  # verhindert Rate-Limits bei DB-Updates

jobservice:
  max_job_workers: 10

log:
  level: info
  local:
    rotate_count: 50
    rotate_size: 200M
    location: /var/log/harbor

Alle Clients müssen den hostname erreichen, Harbor nutzt ihn für Tokens und Callbacks. harbor_admin_password gilt nur beim ersten Start, spätere Änderungen erfolgen in der Web-UI.

Verifizieren: grep -E "^hostname|admin_password|^ port" harbor.yml zeigt Ihre Werte, der Hostname ist weder localhost noch 127.0.0.1 oder 0.0.0.0.

Schritt 3: Installation ausführen

Das Skript prüft Docker, erzeugt Secrets und docker-compose.yml und zieht die Images.

# Mit Trivy-Vulnerability-Scanner installieren (empfohlen)
sudo ./install.sh --with-trivy

--with-trivy startet zusätzlich den trivy-adapter und registriert ihn als Standard-Scanner. Am Ende startet es Harbor mit docker compose up -d.

Verifizieren: docker compose ps im Verzeichnis harbor/ zeigt alle Dienste als Up oder Up (healthy):

docker compose ps

Erwartete Ausgabe (gekürzt):

NAME                  IMAGE                                    STATUS
harbor-core           goharbor/harbor-core:v2.15.2             Up (healthy)
harbor-db             goharbor/harbor-db:v2.15.2               Up (healthy)
harbor-jobservice     goharbor/harbor-jobservice:v2.15.2       Up (healthy)
harbor-log            goharbor/harbor-log:v2.15.2              Up (healthy)
harbor-portal         goharbor/harbor-portal:v2.15.2           Up (healthy)
nginx                 goharbor/nginx-photon:v2.15.2            Up (healthy)
redis                 goharbor/valkey-photon:v2.15.2           Up (healthy)
registry              goharbor/registry-photon:v2.15.2         Up (healthy)
registryctl           goharbor/harbor-registryctl:v2.15.2      Up (healthy)
trivy-adapter         goharbor/trivy-adapter-photon:v2.15.2    Up (healthy)

Schritt 4: Web-UI aufrufen und Erst-Einrichtung

Öffnen Sie http://192.168.1.100 (Ihr Hostname) im Browser. Harbor zeigt die Anmeldeseite.

1. Benutzername: admin
2. Passwort: Wert von harbor_admin_password

Ändern Sie nach der ersten Anmeldung sofort das Admin-Passwort: Admin-Menü (oben rechts) → Change Password. Danach:

1. Projekt anlegen: Projects → New Project, z. B. meinprojekt (öffentlich oder privat)
2. Benutzer anlegen: Administration → Users → New User und dem Projekt eine Rolle zuweisen (Developer, Maintainer etc.)
3. Trivy-Scanner prüfen: Administration → Interrogation Services: Trivy ist als Standard-Scanner aufgeführt und erreichbar

Verifizieren: Prüfen Sie die Erreichbarkeit per curl:

curl -I http://192.168.1.100
# Erwartete Antwort: HTTP/1.1 200 OK oder 302 Found (Weiterleitung zur Login-Seite)

Zusätzlich zeigt docker compose logs core | grep -i error keine Fehler. (Dienstname core, nicht Containername harbor-core).

Schritt 5: Docker-Client konfigurieren und erstes Image pushen

Bei reinem HTTP (Test) tragen Sie die Registry beim Client als „insecure“ ein. Achtung: Der Neustart des Docker-Dienstes stoppt kurz alle Container dieses Hosts.

# /etc/docker/daemon.json anpassen (HTTP-only, nur für Test/Entwicklung)
sudo nano /etc/docker/daemon.json
{
  "insecure-registries": ["192.168.1.100"]
}
sudo systemctl restart docker

Bei HTTPS mit eigener CA kopieren Sie stattdessen das CA-Zertifikat in das Zertifikatsverzeichnis von Docker (ohne Neustart wirksam):

sudo mkdir -p /etc/docker/certs.d/192.168.1.100
sudo cp /data/cert/ca.crt /etc/docker/certs.d/192.168.1.100/

Melden Sie sich an und pushen Sie das erste Image:

# Bei Harbor anmelden
docker login 192.168.1.100
# Username: admin
# Password: (Ihr Admin-Passwort)

# Beliebiges lokales Image mit dem Harbor-Pfad taggen
# Schema: <hostname>/<projekt>/<imagename>:<tag>
docker tag nginx:latest 192.168.1.100/meinprojekt/nginx:latest

# Image in die Harbor-Registry pushen
docker push 192.168.1.100/meinprojekt/nginx:latest

# Image aus der Registry ziehen
docker pull 192.168.1.100/meinprojekt/nginx:latest

Das Projekt meinprojekt muss vorher in der Web-UI angelegt sein.

Verifizieren: Öffnen Sie im Browser Projects → meinprojekt → Repositories. Das Image erscheint mit Tag, Größe und nach dem Trivy-Scan mit einem Schwachstellenbericht. Alternativ per API:

curl -u 'admin:MeinSicheresPasswort123!' \
  http://192.168.1.100/api/v2.0/projects/meinprojekt/repositories
# Erwartete Antwort: JSON-Array mit dem nginx-Repository

Schritt 6: HTTPS für den Produktionsbetrieb einrichten

Im Produktivbetrieb ist HTTPS Pflicht, mit selbst-signiertem oder öffentlichem Zertifikat. Zertifikate mit certbot beschreibt Let's Encrypt mit certbot – TLS-Zertifikate ohne Reverse-Proxy.

Für ein selbst-signiertes Zertifikat:

sudo mkdir -p /data/cert
cd /data/cert

# CA-Zertifikat erstellen
openssl genrsa -out ca.key 4096
openssl req -x509 -new -nodes -sha512 -days 3650 \
  -subj "/C=DE/ST=Bayern/L=Muenchen/O=MeinUnternehmen/CN=192.168.1.100" \
  -key ca.key -out ca.crt

# Server-Zertifikat erstellen
openssl genrsa -out yourdomain.key 4096
openssl req -sha512 -new \
  -subj "/C=DE/ST=Bayern/L=Muenchen/O=MeinUnternehmen/CN=192.168.1.100" \
  -key yourdomain.key -out yourdomain.csr

# v3.ext-Datei für SAN erstellen
cat > v3.ext <<EOF
authorityKeyIdentifier=keyid,issuer
basicConstraints=CA:FALSE
keyUsage=digitalSignature,nonRepudiation,keyEncipherment,dataEncipherment
extendedKeyUsage=serverAuth
subjectAltName=IP:192.168.1.100
EOF

# Zertifikat signieren
openssl x509 -req -sha512 -days 3650 \
  -extfile v3.ext -CA ca.crt -CAkey ca.key -CAcreateserial \
  -in yourdomain.csr -out yourdomain.crt

Aktivieren Sie dann HTTPS in harbor.yml (im harbor/-Verzeichnis):

hostname: 192.168.1.100

# http-Block entfernen oder auskommentieren
# http:
#   port: 80

https:
  port: 443
  certificate: /data/cert/yourdomain.crt
  private_key: /data/cert/yourdomain.key

Erzeugen Sie die Konfiguration nach jeder Änderung an harbor.yml neu:

cd /path/to/harbor
sudo ./prepare
docker compose down
docker compose up -d

Verifizieren: curl -k -I https://192.168.1.100 muss HTTP/2 200 oder HTTP/1.1 302 Found zurückgeben. Mit dem CA-Zertifikat ohne -k: curl --cacert /data/cert/ca.crt -I https://192.168.1.100.

Schritt 7: Harbor verwalten – Lifecycle-Management

Führen Sie alle Befehle im Verzeichnis harbor/ aus, dort liegt die docker-compose.yml:

cd /path/to/harbor

# Status aller Dienste anzeigen
docker compose ps

# Logs eines Dienstes verfolgen (Dienstname, z. B. core)
docker compose logs -f core

# Harbor stoppen (Daten bleiben erhalten)
docker compose stop

# Harbor wieder starten
docker compose start

# Alle Container neu starten (nach Konfigurationsänderung)
docker compose down
docker compose up -d

# ACHTUNG: -v löscht auch alle Named Volumes (Datenverlust!)
# docker compose down -v  # NUR für komplettes Reset/Neuinstallation verwenden

Nach Änderungen an harbor.yml führen Sie vor dem Neustart sudo ./prepare aus, sonst bleibt die alte Konfiguration aktiv.

Verifizieren: Nach dem Neustart zeigt docker compose ps alle Dienste als Up, docker compose logs core | tail -20 enthält keine Fehler.

Schritt 8: Harbor auf eine neue Version aktualisieren

Ablauf laut offizieller Upgrade-Doku. Die Datenbankmigration übernimmt core beim Start. Ab v2.15.2 hebt harbor-db die interne Datenbank beim ersten Start per pg_upgrade von PostgreSQL 15 auf 18, das verlängert den Start.

# 1. Alte Instanz stoppen
cd /opt/harbor
docker compose down

# 2. Installer-Verzeichnis und Datenbank sichern (Pflicht)
sudo mv /opt/harbor /opt/backup/harbor
sudo cp -a /data/database /opt/backup/

# 3. Neuen Installer laden, prüfen (Schritt 1) und entpacken
cd /opt
wget https://github.com/goharbor/harbor/releases/download/vX.Y.Z/harbor-online-installer-vX.Y.Z.tgz
tar xzvf harbor-online-installer-vX.Y.Z.tgz

# 4. Alte harbor.yml übernehmen und auf das neue Schema migrieren
cp /opt/backup/harbor/harbor.yml /opt/harbor/harbor.yml
docker run -it --rm -v /:/hostfs goharbor/prepare:vX.Y.Z migrate -i /opt/harbor/harbor.yml

# 5. Installer ausführen
cd /opt/harbor
sudo ./install.sh --with-trivy

vX.Y.Z ist die Zielversion. Bei Daten mit Umlauten empfiehlt das Projekt nach dem Wechsel auf PostgreSQL 18 reindexdb --all-databases -U postgres im Container harbor-db im Wartungsfenster.

Verifizieren: docker compose ps zeigt alle Dienste als Up, die Images tragen den neuen Tag. Die Version zeigt die Web-UI über das Fragezeichen-Menü → About.

Troubleshooting / Typische Fehler

1. hostname ist localhost/127.0.0.1/0.0.0.0: Symptom: Die Anmeldung schlägt fehl. Lösung: In harbor.yml eine echte IP-Adresse oder einen FQDN eintragen, dann sudo ./prepare && docker compose down && docker compose up -d.
2. docker login: „certificate signed by unknown authority“: Docker kennt die eigene CA nicht. Lösung: ca.crt nach /etc/docker/certs.d/192.168.1.100/ kopieren (Schritt 5).
3. harbor-core bleibt im Restart-Loop: PostgreSQL ist noch nicht bereit. Prüfen Sie docker compose logs postgresql und nach 30 bis 60 Sekunden erneut docker compose ps.
4. harbor.yml geändert, aber Harbor zeigt alte Konfiguration: Führen Sie sudo ./prepare aus, danach docker compose down && docker compose up -d.
5. Trivy-Vulnerability-DB-Update schlägt fehl (Rate-Limit): Lösung: GitHub-Token in harbor.yml unter trivy.github_token eintragen.
6. Image-Push mit „413 Request Entity Too Large“: Ein vorgelagerter Reverse-Proxy begrenzt die Größe. Lösung: client_max_body_size 0; in der Nginx-Konfiguration oder das Traefik-Äquivalent setzen.
7. Admin-Passwort nach Neuinstallation falsch: harbor_admin_password in harbor.yml gilt nur beim ersten Start. Ändern Sie das Passwort in der Web-UI.
8. Intermediate-Zertifikat nicht erkannt: Hängen Sie das Zwischenzertifikat an das Serverzertifikat an: cat intermediate.pem >> yourdomain.crt.

Häufige Fragen

Kann ich Harbor hinter einem bestehenden Reverse-Proxy (Traefik, Nginx) betreiben?

Ja. Setzen Sie http.port auf einen freien Port (z. B. 8080), lassen Sie den Proxy HTTPS terminieren und tragen Sie unter external_url die öffentliche HTTPS-URL ein. Doppelte X-Forwarded-Proto-Header stören die Token-Validierung. Traefik beschreibt Traefik als Docker-Reverse-Proxy mit automatischem HTTPS.

Was ist der Unterschied zwischen --with-trivy und einer Installation ohne diesen Parameter?

Ohne --with-trivy prüft Harbor Images nicht auf CVEs. Nachträglich aktivieren Sie Trivy, indem Sie sudo ./install.sh --with-trivy erneut im Verzeichnis harbor/ ausführen.

Kann ich eine externe PostgreSQL-Datenbank oder einen externen Redis verwenden?

Ja. In harbor.yml ersetzen Sie den database-Block durch external_database und analog external_redis. Die internen Container harbor-db und redis entfallen dann.

Wie aktiviere ich Prometheus-Metriken für Harbor?

In harbor.yml den metric-Block aktivieren und konfigurieren, dann sudo ./prepare und Neustart:

metric:
  enabled: true
  port: 9090
  path: /metrics

Der harbor-exporter-Container stellt danach Metriken auf Port 9090 bereit. Prometheus und Grafana beschreibt cAdvisor mit Prometheus: Docker-Container-Metriken sammeln und in Grafana visualisieren.

Wie unterstützt Harbor Image-Signierung?

Harbor v2.15 unterstützt Signaturen mit Cosign (Sigstore) und Notation (CNCF). Das alte Notary (--with-notary) ist entfernt; Anleitungen mit diesem Parameter sind veraltet.

Wie wird Garbage Collection ausgeführt?

Nicht mehr referenzierte Blobs belegen Speicher, bis die Garbage Collection (GC) läuft. Unter Administration → Garbage Collection starten Sie sie manuell oder per Zeitplan. Wichtig: Während der GC ist der Push temporär gesperrt.

Fazit

Harbor eignet sich, wenn Sie eine private Registry mit Schwachstellen-Scans, RBAC, Signaturen und Replikation brauchen. Der Installer erzeugt die Compose-Datei samt Secrets und Healthchecks selbst; Änderungen laufen deshalb immer über harbor.yml und prepare. Sichern Sie vor jedem Update /data/database. Scans schon in der CI/CD-Pipeline beschreibt Docker-Images auf Schwachstellen scannen mit Trivy.

Weiterführende Anleitungen und Quellen

1. Docker und Docker Compose auf Linux installieren – die Self-Hosting-Grundlage
2. Traefik als Docker-Reverse-Proxy mit automatischem HTTPS einrichten
3. Docker-Images auf Schwachstellen scannen mit Trivy: CVE-Check, SBOM und automatische Scans
4. cAdvisor mit Prometheus: Docker-Container-Metriken sammeln und in Grafana visualisieren
5. Docker Compose absichern: Secrets, Healthchecks, Non-Root und Read-Only für den Produktivbetrieb

Offizielle Quellen: Harbor-Dokumentation unter goharbor.io/docs. Releases und Changelogs auf der GitHub-Releases-Seite; bei Abweichungen zur Doku-Website gelten die Release Notes. Upgrade-Ablauf: Upgrade Harbor and Migrate Data.