Docker-Hub-Images mit deinem eigenen Docker-Hub-Token über den Abhängigkeits-Proxy ziehen

fremforge zieht Docker-Hub-Images nicht mit einem gemeinsamen Konto in deinem Auftrag. Die Nutzungsbedingungen von Docker erlauben den Zugriff für deine eigenen internen Zwecke, und Docker Hub begrenzt anonyme Pulls pro IP-Adresse, geteilt von allen hinter dieser Adresse. Deshalb funktioniert Docker Hub so wie beim Abhängigkeits-Proxy von GitLab und den Pull-Through-Caches von Amazon ECR: Deine Organisation bringt ihren eigenen Docker-Hub-Token mit, und der Abhängigkeits-Proxy zieht und speichert Images damit.

Du hast dann zwei Wege, ein Docker-Hub-Image zu ziehen:

Von fremforge gehostete Runner verwenden keinen gemeinsamen Docker-Hub-Mirror mehr. Solange deine Organisation ihren Docker-Hub-Token nicht hinterlegt hat, ist ein einfaches docker pull node:24 in einem Workflow ein anonymer Pull direkt von Docker Hub, der auf das Limit von Docker für die Adresse des Runners zählt. Sobald der Token hinterlegt ist, und mit eingeschaltetem Runner-Pull-Through (Standard), leitet der Docker-Daemon des Runners Docker-Hub-Pulls in deinen Jobs mit diesem Token über deinen Proxy, ohne dass sich die Image-Namen ändern, außer in Jobs aus Fork-Pull-Requests. Siehe Gehostete Runner.

Bevor du anfängst

• Der Abhängigkeits-Proxy muss für die Organisation eingeschaltet sein. Er ist in jedem Tarif verfügbar und standardmäßig an; ein Owner, der ihn ausgeschaltet hat, schaltet ihn unter Build und Deployment › Abhängigkeits-Proxy wieder ein (PUT /orgs/{org}/dependency-proxy mit "enabled": true).
• Du musst Owner der Organisation sein, um Zugangsdaten zu hinterlegen.

Einen Docker-Hub-Zugriffstoken erstellen

1. Melde dich bei Docker Hub mit dem Konto an, das der Proxy verwenden soll: Ein Dienstkonto deines Unternehmens ist besser als das einer Person.
2. Geh zu Account settings > Personal access tokens und wähle Generate new token.
3. Benenne ihn danach, wo er verwendet wird, zum Beispiel fremforge dependency proxy, und setze die Zugriffsberechtigungen auf Public Repo Read-only. Der Proxy liest immer nur.
4. Kopiere den Token. Docker Hub zeigt ihn nur einmal an.

Ein Organisations-Zugriffstoken einer Docker-Hub-Organisation funktioniert genauso.

Als docker.io-Upstream-Zugangsdaten deiner Organisation hinterlegen

In der Konsole: Build und Deployment › Abhängigkeits-Proxy › Upstream-Zugangsdaten, unter Zugangsdaten hinzufügen. Wähle die Registry docker.io, setze Anmeldung auf Benutzername und Passwort oder Token, gib den Docker-Hub-Benutzernamen und den Token als Passwort ein und wähle Hinzufügen. Verbindung testen lässt den Proxy sich sofort damit bei Docker Hub anmelden.

Mit der API (ein Token mit policy:write, von einem Owner der Organisation):

curl -sS -X POST "https://frem.sh/_app/api/v1/orgs/<org>/dependency-proxy/upstreams" \
  -H "Authorization: Bearer $FREMFORGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"host": "docker.io", "auth_type": "basic", "username": "<docker-hub-user>", "password": "<docker-hub-token>"}'

Die Antwort enthält die id der Zugangsdaten und einen Fingerabdruck, nie das Secret. Teste sie mit POST /orgs/<org>/dependency-proxy/upstreams/<id>/test, schalte sie aus oder ersetze das Secret mit PATCH /orgs/<org>/dependency-proxy/upstreams/<id>, und entferne sie mit DELETE.

Das Secret kann nur geschrieben werden: Es wird beim Speichern versiegelt und nie zurückgegeben, geloggt oder ins Audit-Log geschrieben. Das Audit-Log hält fest, wer die Zugangsdaten hinzugefügt, geändert oder entfernt hat.

Über den Proxy ziehen

Melde dich bei frem.sh mit deinem fremforge-Benutzernamen und einem persönlichen Zugriffstoken mit read:package an und ziehe dann mit dem Präfix des Abhängigkeits-Proxys:

docker login frem.sh -u <your-user>
docker pull frem.sh/<org>/dependency-proxy/docker.io/library/node:24-bookworm-slim

Offizielle Images liegen auf Docker Hub unter library/, also wird node:24 zu frem.sh/<org>/dependency-proxy/docker.io/library/node:24. Andere Images behalten ihren Namespace: pgvector/pgvector:pg17 wird zu frem.sh/<org>/dependency-proxy/docker.io/pgvector/pgvector:pg17.

Du kannst auch per Digest ziehen, und ein gepinnter Multi-Plattform-Digest funktioniert unverändert:

FROM frem.sh/<org>/dependency-proxy/docker.io/library/node:24-bookworm-slim@sha256:<digest>

In Forgejo Actions

Ein Job kann sich mit seinem eigenen Job-Token anmelden. Er zieht nur über den Abhängigkeits-Proxy der Organisation seines eigenen Repositorys.

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: log in to the dependency proxy
        run: echo "${{ github.token }}" | docker login frem.sh -u "${{ github.actor }}" --password-stdin
      - run: docker build -t app .

Stehen die FROM-Zeilen des Dockerfiles auf dem Präfix frem.sh/<org>/dependency-proxy/docker.io/, zieht der Build mit dieser Anmeldung über den Proxy.

Ein Job, der von einem Pull Request aus einem Fork ausgelöst wird, läuft nie mit den Zugangsdaten deiner Organisation und kann daher keine docker.io-Images über den Proxy ziehen. Ziehe diese direkt von Docker Hub.

Ohne Zugangsdaten

Hat deine Organisation keine eingeschalteten docker.io-Zugangsdaten, antwortet ein Pull über den Proxy mit 403 DENIED:

docker.io needs your organisation's own Docker Hub credentials (decision D1): an organisation
owner adds them under Organisation settings > Dependency proxy > Upstream credentials

Der Proxy weicht nicht auf einen anonymen Docker-Hub-Pull aus. Hinterlege entweder Zugangsdaten oder referenziere das Image direkt (docker.io/...), was ein anonymer Pull unter dem Limit von Docker Hub für anonyme Pulls ist.

Andere Registrys verhalten sich anders: ghcr.io und quay.io funktionieren über den Proxy anonym, wenn du keine Zugangsdaten für sie hast, und verwenden deine, wenn du welche hast.

Prüfen, ob es funktioniert

• Ziehe ein Image über den Proxy und sieh dir dann die Seite Usage deines Docker-Hub-Kontos an: Der Pull wird dort einmal gezählt. Ein zweiter Pull desselben Images wird aus dem Cache bedient.
• Schlägt ein Pull mit 503 und your organisation’s docker.io credential could not be used fehl, ließen sich die hinterlegten Zugangsdaten nicht öffnen. Das ist ein Fehler bei fremforge, und er wird geloggt.