Eigene Docker-Registry betreiben

Was dieser Artikel über Docker-Registry behandelt

• Was eine Docker-Registry ist und wann eine eigene sinnvoll ist.
• Wie man die offizielle Registry in Docker betreibt.
• Wie man Images pusht und pulled.
• Authentifizierung, TLS und Sicherheit.
• Tipps für Backups und Wartung.

Einleitung: Eigene Docker-Registry betreiben

Eine Docker-Registry ist ein Speicherort für Docker-Images. Standardmässig werden Images von Docker Hub bezogen, aber manchmal möchte man eigene Images lokal oder im internen Netzwerk bereitstellen. Eine eigene Registry ist nützlich für CI/CD, isolierte Umgebungen, Datenschutz oder wenn Docker Hub nicht erreichbar sein soll.

Dieser Artikel zeigt, wie man die offizielle Docker-Registry lokal oder im Homelab betreibt.

Wichtige Begriffe

• Registry: Speicherort für Docker-Images.
• Repository: Sammlung von Images unter einem Namen.
• Tag: Versionskennzeichnung eines Images.
• Push: Hochladen eines Images in die Registry.
• Pull: Herunterladen eines Images aus der Registry.
• TLS: Verschlüsselung der Verbindung.
• Basic Auth: Benutzername und Passwort für den Zugriff.
• Garbage Collection: Bereinigung nicht referenzierter Layer.

Wann ist eine eigene Registry sinnvoll?

• Eigene Images im internen Netzwerk verteilen.
• CI/CD-Pipelines beschleunigen.
• Docker Hub-Limitierungen umgehen.
• Daten nicht in öffentliche Registries laden.
• Air-gapped Umgebungen versorgen.
• Build-Cache zwischen Hosts teilen.

Registry starten

Die offizielle Registry läuft als einfacher Container:

docker run -d -p 5000:5000 --name registry registry:2

Test:

curl http://localhost:5000/v2/_catalog

Image taggen und pushen

Ein bestehendes Image umbenennen und hochladen:

docker tag mein-image:latest localhost:5000/mein-image:latest
docker push localhost:5000/mein-image:latest

Image pullen

docker pull localhost:5000/mein-image:latest

Persistent mit Volume

docker run -d -p 5000:5000 --name registry \
  -v registry-data:/var/lib/registry \
  registry:2

TLS aktivieren

Für Produktion oder Fernzugriff sollte die Registry per TLS gesichert sein. Man kann ein Zertifikat von einer CA oder ein selbst signiertes Zertifikat verwenden.

Selbstsigniertes Zertifikat

mkdir -p certs
openssl req -newkey rsa:4096 -nodes -sha256 -keyout certs/registry.key -x509 -days 365 -out certs/registry.crt

Registry mit Zertifikat:

docker run -d -p 5000:5000 --name registry \
  -v $(pwd)/certs:/certs \
  -v registry-data:/var/lib/registry \
  -e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/registry.crt \
  -e REGISTRY_HTTP_TLS_KEY=/certs/registry.key \
  registry:2

Auf dem Client muss das Zertifikat akzeptiert werden:

mkdir -p /etc/docker/certs.d/localhost:5000
cp registry.crt /etc/docker/certs.d/localhost:5000/ca.crt

Authentifizierung

Eine einfache Basic Auth mit htpasswd:

mkdir auth
docker run --rm --entrypoint htpasswd httpd:2 -Bbn admin meinpasswort > auth/htpasswd

Registry mit Auth:

docker run -d -p 5000:5000 --name registry \
  -v $(pwd)/auth:/auth \
  -e REGISTRY_AUTH=htpasswd \
  -e REGISTRY_AUTH_HTPASSWD_REALM="Registry Realm" \
  -e REGISTRY_AUTH_HTPASSWD_PATH=/auth/htpasswd \
  -v registry-data:/var/lib/registry \
  registry:2

Login:

docker login localhost:5000

Registry mit Compose

services:
  registry:
    image: registry:2
    container_name: registry
    ports:
      - "127.0.0.1:5000:5000"
    volumes:
      - registry-data:/var/lib/registry
      - ./certs:/certs
      - ./auth:/auth
    environment:
      - REGISTRY_HTTP_TLS_CERTIFICATE=/certs/registry.crt
      - REGISTRY_HTTP_TLS_KEY=/certs/registry.key
      - REGISTRY_AUTH=htpasswd
      - REGISTRY_AUTH_HTPASSWD_REALM=Registry Realm
      - REGISTRY_AUTH_HTPASSWD_PATH=/auth/htpasswd
    restart: unless-stopped

volumes:
  registry-data:

Garbage Collection

Nicht mehr referenzierte Layer können Speicher belegen. Ein Cleanup:

docker exec registry bin/registry garbage-collect /etc/docker/registry/config.yml

Backup

Die Registry-Daten liegen in /var/lib/registry. Ein einfaches Backup:

docker run --rm -v registry-data:/data -v $(pwd):/backup alpine tar -czf /backup/registry-backup.tar.gz -C /data .

Sicherheit

• TLS unbedingt für Netzwerkzugriff verwenden.
• Authentifizierung aktivieren.
• Registry nicht öffentlich ins Internet stellen.
• Zugang über VPN oder Tailscale beschränken.
• Regelmässig Backups und Updates einspielen.
• Logging aktivieren.

Typische Stolpersteine

• Kein TLS: Docker blockiert in neueren Versionen unsichere Registries.
• Insecure Registry: Zwar möglich, aber nicht empfohlen.
• Falsche Tag-Namen: Image-Name muss Registry-Host enthalten.
• Auth nicht konfiguriert: Push wird ohne Login abgelehnt.
• Speicher läuft voll: Garbage Collection fehlt.
• Zertifikat nicht vertraut: Client braucht CA-Zertifikat.

Weiterführende Links und Infos

• BotServ.de Docker Befehle
• BotServ.de Docker Volumes
• BotServ.de Docker Backup
• BotServ.de Docker Sicherheit
• BotServ.de Tailscale Grundlagen

FAQ: Docker-Registry

Brauche ich eine eigene Registry? Wenn viele eigene Images intern verteilt werden, ja. Für gelegentliche Images reicht Docker Hub.

Kann ich die Registry öffentlich machen? Nur mit TLS, Auth und Rate-Limiting. Besser intern halten.

Ist die Registry skalierbar? Für kleine Setups reicht ein einzelner Container. Für grössere Szenarien gibt es Distribution oder Harbor.

Wie lösche ich alte Images? Per API oder Garbage Collection. Einzelne Tags können über die Registry-API entfernt werden.

Was ist Harbor? Ein erweitertes Open-Source-Registry-Projekt mit UI, Auth und Sicherheits-Scanning.

Quellen und weiterführende Literatur

• Docker Registry: https://distribution.github.io/distribution/
• Docker Registry Image: https://hub.docker.com/_/registry
• Harbor: https://goharbor.io/

Zusammenfassung: Eigene Docker-Registry betreiben

Eine eigene Docker-Registry ermöglicht es, Images lokal oder im internen Netzwerk bereitzustellen. Sie lässt sich schnell als Container starten, sollte aber für Produktions- oder Fernzugriff mit TLS und Authentifizierung abgesichert werden. Wichtig sind saubere Tag-Namen, regelmässige Backups, Garbage Collection und ein eingeschränkter Netzwerkzugriff. Wer die Registry richtig betreibt, spart Bandbreite, beschleunigt Deployments und behält die Kontrolle über eigene Images.