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

Wer Container-Images intern verwalten will, ohne sich auf Docker Hub oder einen Cloud-Anbieter zu verlassen, braucht eine private Registry – und Harbor ist dabei der Enterprise-Standard. Mit über 28.000 GitHub-Stars und dem Status als CNCF Graduated Project (der höchsten Reifestufe in der Cloud Native Landscape) ist Harbor mehr als nur ein Speicherort für Docker-Images: Es ist ein vollständiges Image-Management-System mit integriertem Trivy-Vulnerability-Scanning, rollenbasierter Zugriffskontrolle (RBAC), Image-Signierung via Cosign/Notation, Tag-Immutabilität und Replikation zu anderen Registries. Diese Anleitung richtet sich an Entwicklungsteams, KMU-Admins und ambitionierte Selfhoster, die Harbor v2.15.1 per Docker Compose auf einem Linux-Host aufsetzen wollen – plattformneutral, produktionsnah und mit Verifikation nach jedem Schritt.

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 ohne Bindestrich); wie du beides installierst, erklärt die Anleitung 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 die HTTPS-Zertifikat-Generierung (meist vorinstalliert); wget oder curl zum Herunterladen des Installers.
5. Optional für Produktion: TLS-Zertifikat (Let's Encrypt oder selbst-signiert); einen Reverse-Proxy wie Traefik oder Nginx kannst du vorschalten – das beschreibt Traefik als Docker-Reverse-Proxy einrichten.
6. Internetverbindung für den Online-Installer (Harbor-Images werden von Docker Hub gezogen).

Harbor-Eckdaten im Überblick

Schritt 1: Installer herunterladen und Signatur prüfen

Harbor wird ausschließlich über den offiziellen Installer ausgerollt. Lade den Online-Installer (v2.15.1) herunter und prüfe optional die GPG-Signatur – das ist gerade im Unternehmensumfeld empfehlenswert:

# Installer und Signaturdatei herunterladen
wget https://github.com/goharbor/harbor/releases/download/v2.15.1/harbor-online-installer-v2.15.1.tgz
wget https://github.com/goharbor/harbor/releases/download/v2.15.1/harbor-online-installer-v2.15.1.tgz.asc

# GPG-Signatur prüfen (empfohlen)
gpg --keyserver keyserver.ubuntu.com --recv-keys 644FF454C0B4115C
gpg --verify harbor-online-installer-v2.15.1.tgz.asc harbor-online-installer-v2.15.1.tgz

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

Das Verzeichnis harbor/ enthält jetzt unter anderem das Template harbor.yml.tmpl, das Installer-Skript install.sh und das Konfigurationsskript prepare.

Verifizieren: Führe ls harbor/ aus – du solltest folgende Dateien sehen: harbor.yml.tmpl, install.sh, prepare, common/, LICENSE. Die GPG-Prüfung endet mit gpg: Good signature from "Harbor-sign ...".

Schritt 2: harbor.yml konfigurieren

Harbor verwendet keine klassische .env-Datei für Docker Compose. Alle Konfigurationsparameter – Hostname, Passwörter, HTTPS, Trivy-Einstellungen – leben in einer einzigen Datei: harbor.yml. Das prepare-Skript überträgt diese Werte später in die generierten Container-Konfigurationen.

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

Die folgende Minimalkonfiguration eignet sich für Test- und Entwicklungsumgebungen (HTTP-only). Für den Produktionsbetrieb solltest du den HTTPS-Block aktivieren – dazu weiter unten mehr.

# harbor.yml – Minimalkonfiguration (HTTP, Test/Entwicklung)
# WICHTIG: Ersetze 192.168.1.100 durch deine echte IP oder deinen FQDN.
# 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: dein_github_token  # Verhindert Rate-Limiting bei DB-Updates

jobservice:
  max_job_workers: 10

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

Wichtige Hinweise zu den Parametern: Der hostname wird intern von Harbor für Token-Validierung und API-Callbacks verwendet – er muss von allen Clients erreichbar sein. Das harbor_admin_password gilt nur beim allerersten Start; danach wird es ignoriert und muss im Web-UI geändert werden.

Verifizieren: Prüfe deine Konfiguration mit grep -E "hostname|admin_password|port" harbor.yml – alle drei Werte müssen auf deine Umgebung angepasst sein. Stelle sicher, dass der Hostname keine der verbotenen Werte (localhost, 127.0.0.1, 0.0.0.0) enthält.

Schritt 3: Installation ausführen

Das Installer-Skript übernimmt alle weiteren Schritte automatisch: Es prüft die Docker/Compose-Version, generiert kryptografisch sichere Secrets (CORE_SECRET, JOBSERVICE_SECRET, REGISTRY_HTTP_SECRET), erstellt die docker-compose.yml aus dem Jinja-Template und zieht alle Harbor-Images von Docker Hub.

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

Der Parameter --with-trivy aktiviert den trivy-adapter-Container und registriert Trivy automatisch als Standard-Scanner in Harbor. Ohne diesen Flag ist kein Vulnerability-Scanning möglich. Der Download aller Images kann je nach Internetverbindung 5–15 Minuten dauern.

Am Ende des Skripts startet Harbor automatisch via docker compose up -d. Die generierte docker-compose.yml liegt danach im harbor/-Verzeichnis.

Verifizieren: Führe docker compose ps im harbor/-Verzeichnis aus. Alle Dienste müssen den Status Up oder Up (healthy) zeigen:

docker compose ps

Erwartete Ausgabe (gekürzt):

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

Schritt 4: Web-UI aufrufen und Erst-Einrichtung

Öffne deinen Browser und navigiere zu http://192.168.1.100 (ersetze die IP durch deinen konfigurierten Hostname). Du wirst zur Harbor-Anmeldeseite weitergeleitet.

1. Benutzername: admin
2. Passwort: Das in harbor.yml unter harbor_admin_password gesetzte Passwort

Nach dem ersten Login solltest du das Admin-Passwort sofort im Web-UI ändern: Admin-Menü (oben rechts) → Change Password. Außerdem empfehlen sich folgende erste Schritte in der UI:

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 – der Trivy-Adapter sollte als Standard-Scanner aufgelistet und verbunden sein

Verifizieren: Prüfe 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: docker compose logs -f harbor-core – es sollten keine ERROR-Meldungen erscheinen. Ein INFO ... Server started on 0.0.0.0:8080 zeigt, dass die Core-API bereit ist.

Schritt 5: Docker-Client konfigurieren und erstes Image pushen

Damit du Images in deine neue Harbor-Registry pushen kannst, muss der Docker-Daemon den Endpunkt kennen. Bei HTTP-Betrieb (Test/Entwicklung) trägst du die Registry als „insecure" ein:

# /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

Für den Produktionsbetrieb mit HTTPS (selbst-signiertes Zertifikat) kopierst du das CA-Zertifikat stattdessen in das Docker-Zertifikatsverzeichnis:

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/
sudo systemctl restart docker

Jetzt kannst du dich anmelden und das erste Image pushen:

# Bei Harbor anmelden
docker login 192.168.1.100
# Username: admin
# Password: (dein konfiguriertes 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 in der Harbor-UI vorab existieren oder der Administrator muss Auto-Create Projects on Push aktiviert haben.

Verifizieren: Öffne im Browser Projects → meinprojekt → Repositories. Das gepushte Image erscheint dort mit Tag, Größe und – nach dem automatischen Trivy-Scan – einem Vulnerability-Report. 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

HTTP reicht für lokale Tests, aber für den Produktionseinsatz ist HTTPS Pflicht. Du kannst entweder ein selbst-signiertes Zertifikat erstellen oder ein gültiges Zertifikat (z. B. von Let's Encrypt) einbinden. Wie du TLS-Zertifikate mit certbot generierst, erklärt 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

Aktiviere 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

Nach jeder Änderung an harbor.yml muss die Konfiguration neu generiert werden:

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

Alle Lifecycle-Befehle werden im harbor/-Verzeichnis ausgeführt, da dort die generierte docker-compose.yml liegt:

cd /path/to/harbor

# Status aller Dienste anzeigen
docker compose ps

# Logs eines einzelnen Dienstes verfolgen (z. B. Core-API)
docker compose logs -f harbor-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 einer Änderung in harbor.yml immer erst sudo ./prepare ausführen, bevor die Container neugestartet werden – sonst bleibt die alte Konfiguration aktiv.

Verifizieren: Nach dem Neustart docker compose ps – alle Dienste müssen wieder Up zeigen. Logs mit docker compose logs harbor-core | tail -20 prüfen.

Schritt 8: Harbor auf eine neue Version aktualisieren

Harbor-Updates folgen einem klar definierten Ablauf. Das Migrations-Skript für die Datenbank läuft automatisch beim ersten Start der neuen Version:

# 1. Datenbank und /data sichern (PFLICHT vor jedem Update!)
# Siehe: https://s-edv.com/anleitungen/mysql-postgresql-backup-automatisieren-cron-cloud

# 2. Alte Instanz stoppen
cd /path/to/harbor
docker compose down

# 3. Neuen Installer herunterladen und entpacken
cd /opt
wget https://github.com/goharbor/harbor/releases/download/v2.15.1/harbor-online-installer-v2.15.1.tgz
tar xzvf harbor-online-installer-v2.15.1.tgz -C harbor-new/
# Hinweis: Versionsnummer ggf. auf die tatsächlich neue Version anpassen

# 4. harbor.yml aus der alten Installation kopieren und anpassen
cp /path/to/harbor/harbor.yml /opt/harbor-new/harbor/harbor.yml

# 5. Neuen Installer ausführen (Datenbankmigrationen laufen automatisch)
cd /opt/harbor-new/harbor
sudo ./install.sh --with-trivy

Verifizieren: docker compose ps und Browser-Aufruf der Web-UI. Die Harbor-Versionsnummer findest du unter Administration → Configuration → System Settings.

Troubleshooting / Typische Fehler

1. hostname ist localhost/127.0.0.1/0.0.0.0: Harbor-Dienste verwenden den Hostname intern für Token-Validierung und API-Callbacks. Symptom: Login schlägt fehl, Core-API antwortet nicht korrekt. 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": Das Self-Signed-Zertifikat ist dem Docker-Daemon nicht bekannt. Lösung: sudo cp /data/cert/ca.crt /etc/docker/certs.d/192.168.1.100/ und sudo systemctl restart docker. Alternativ für HTTP: "insecure-registries" in /etc/docker/daemon.json.
3. harbor-core bleibt im Restart-Loop: PostgreSQL ist noch nicht bereit. Logs prüfen: docker compose logs postgresql. Harbor hat zwar depends_on mit Health-Checks, aber auf sehr langsamen Systemen kann pg_isready länger dauern. Einfach 30–60 Sekunden warten, dann erneut docker compose ps.
4. harbor.yml geändert, aber Harbor zeigt alte Konfiguration: Die geänderte harbor.yml muss erst per sudo ./prepare in die Container-Konfigdateien übertragen werden. Danach docker compose down && docker compose up -d.
5. Trivy-Vulnerability-DB-Update schlägt fehl (Rate-Limit): Trivy lädt die Datenbank von GitHub; anonyme Anfragen werden schnell gedrosselt. 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 Request-Größe. Lösung: client_max_body_size 0; in der Nginx-Konfiguration oder das Traefik-Äquivalent setzen. Harbor selbst ist für große Images ausgelegt.
7. Admin-Passwort nach Neuinstallation falsch: harbor_admin_password in harbor.yml gilt nur beim allerersten Start – bei bestehender Datenbank hat eine Änderung dort keinen Effekt. Passwort im Web-UI ändern oder Datenbank zurücksetzen.
8. Intermediate-Zertifikat nicht erkannt: Nur das End-Entity-Zertifikat wurde konfiguriert. Lösung: Intermediate an das Domain-Zertifikat anhängen: cat intermediate.pem >> yourdomain.crt.

Häufige Fragen

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

Ja. Setze in harbor.yml den http.port auf einen freien internen Port (z. B. 8080) und lass den Proxy das HTTPS terminieren. Wichtig: Trage den Parameter external_url in harbor.yml auf die öffentliche HTTPS-URL ein, damit Harbor korrekte Links und Tokens generiert. Vermeide doppelte X-Forwarded-Proto-Header – das ist eine häufige Fehlerquelle bei der Token-Validierung. Wie du Traefik einrichtest, erklärt Traefik als Docker-Reverse-Proxy mit automatischem HTTPS.

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

Mit --with-trivy wird der trivy-adapter-Container zusätzlich gestartet und in Harbor als Standard-Scanner registriert. Ohne den Flag ist kein Vulnerability-Scanning möglich – Images werden zwar gespeichert, aber nicht auf CVEs geprüft. Trivy kann auch nachträglich aktiviert werden, indem du sudo ./install.sh --with-trivy erneut im harbor/-Verzeichnis ausführst.

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

Ja. In harbor.yml ersetzt du den database-Block durch external_database (mit Host, Port, Username, Password, ssl-mode) und analog external_redis für Redis. Die internen Container harbor-db und redis werden dann nicht gestartet. Das ist sinnvoll für Hochverfügbarkeits-Setups, bei denen Datenbank und Redis als Cluster betrieben werden.

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. Wie du Prometheus und Grafana-Dashboards einrichtest, zeigt cAdvisor mit Prometheus: Docker-Container-Metriken sammeln und in Grafana visualisieren.

Wie unterstützt Harbor Image-Signierung?

Harbor v2.15.1 unterstützt Image-Signierung via Cosign (OIDC-basiert, sigstore-kompatibel, inklusive Cosign v3 Bundle-Signaturen) und Notation (CNCF-Standard). Das alte Notary-System (--with-notary) wurde in neueren Versionen entfernt – Anleitungen, die noch --with-notary erwähnen, sind veraltet.

Wie wird Garbage Collection ausgeführt?

Nicht mehr referenzierte Image-Blobs belegen dauerhaft Speicherplatz, bis Garbage Collection (GC) ausgeführt wird. In der Harbor-UI unter Administration → Garbage Collection kannst du GC manuell starten oder einen Zeitplan einrichten. Wichtig: Während der GC ist der Push temporär gesperrt.

Fazit

Harbor ist die überzeugendste Open-Source-Lösung, wenn du eine private Container-Registry mit echten Enterprise-Features brauchst: integriertes Vulnerability-Scanning mit Trivy, fein granuliertes RBAC auf Projektebene, Image-Signierung, Tag-Immutabilität und Replikation zu externen Registries. Der Installations-Workflow unterscheidet sich von typischen Docker-Compose-Projekten – statt einer handgepflegten Compose-Datei übernimmt der offizielle Installer die gesamte Orchestrierung. Das wirkt zunächst ungewohnt, ist aber der Grund, warum Harbor so zuverlässig läuft: Die internen Secrets werden automatisch generiert, die Dienstreihenfolge ist korrekt hinterlegt, und Health-Checks sind bereits konfiguriert. Für Teams, die Docker-Images scannen wollen, bevor sie in der Produktion laufen, ist Harbor der direkteste Weg – und mit dem Artikel Docker-Images auf Schwachstellen scannen mit Trivy kannst du Trivy auch direkt in deine CI/CD-Pipeline einbinden, bevor die Images überhaupt in Harbor landen.

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: Die vollständige Harbor-Dokumentation (Installations-Voraussetzungen, HTTPS-Konfiguration, Troubleshooting) findet sich unter goharbor.io/docs. Aktuelle Releases und Changelogs gibt es auf der GitHub-Releases-Seite – diese ist bei Versionsdiskrepanzen immer maßgeblich gegenüber der offiziellen Dokumentationswebseite.