Docker Hub-images ophalen via de dependency-proxy met je eigen Docker Hub-token

fremforge haalt Docker Hub-images niet namens jou op met een gedeeld account. De voorwaarden van Docker staan toegang toe voor je eigen interne doeleinden, en Docker Hub beperkt anonieme pulls per IP-adres, gedeeld door iedereen achter dat adres. Docker Hub werkt daarom zoals de dependency-proxy van GitLab en de pull-through-caches van Amazon ECR het doen: je organisatie brengt haar eigen Docker Hub-token mee, en de dependency-proxy haalt images daarmee op en cachet ze.

Je hebt dan twee manieren om een Docker Hub-image op te halen:

Door fremforge gehoste runners gebruiken geen gedeelde Docker Hub-mirror meer. Zolang je organisatie haar Docker Hub-token niet heeft opgeslagen, is een gewone docker pull node:24 in een workflow een anonieme pull rechtstreeks van Docker Hub, die meetelt voor de limiet van Docker voor het adres van de runner. Heeft ze dat wel gedaan, en staat runner-pull-through aan (de standaard), dan stuurt de Docker-daemon van de runner Docker Hub-pulls in je jobs via je proxy met dat token, zonder dat de imagenamen veranderen, behalve in jobs van pull requests vanuit forks. Zie Gehoste runners.

Voordat je begint

• De dependency-proxy moet aan staan voor de organisatie. Hij is beschikbaar in elk abonnement en staat standaard aan; een eigenaar die hem heeft uitgezet, zet hem weer aan onder Organisatie-instellingen › Proxy voor afhankelijkheden (PUT /orgs/{org}/dependency-proxy met "enabled": true).
• Je moet eigenaar van de organisatie zijn om inloggegevens op te slaan.

Een Docker Hub-toegangstoken aanmaken

1. Log in bij Docker Hub met het account dat de proxy moet gebruiken: een serviceaccount van je bedrijf is beter dan het account van een persoon.
2. Ga naar Account settings > Personal access tokens en kies Nieuw token genereren.
3. Geef het een naam naar de plek waar het wordt gebruikt, bijvoorbeeld fremforge dependency proxy, en zet de toegangsrechten op Public Repo Read-only. De proxy leest alleen.
4. Kopieer het token. Docker Hub toont het maar één keer.

Een organisatietoegangstoken van een Docker Hub-organisatie werkt op dezelfde manier.

Sla het op als docker.io-upstream-inloggegevens van je organisatie

In de console: Organisatie-instellingen › Proxy voor afhankelijkheden › Upstream-inloggegevens, onder Inloggegevens toevoegen. Kies de registry docker.io, zet Zo logt hij in op Gebruikersnaam en wachtwoord of token, vul de Docker Hub-gebruikersnaam in en het token als wachtwoord, en kies Toevoegen. Met Verbinding testen laat je de proxy er nu mee inloggen bij Docker Hub.

Via de API (een token met policy:write, van een eigenaar van de organisatie):

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>"}'

Het antwoord bevat de id van de inloggegevens en een vingerafdruk, nooit het secret. Test ze met POST /orgs/<org>/dependency-proxy/upstreams/<id>/test, zet ze uit of vervang het secret met PATCH /orgs/<org>/dependency-proxy/upstreams/<id>, en verwijder ze met DELETE.

Het secret kan alleen worden geschreven: het wordt bij het opslaan verzegeld en wordt nooit teruggegeven, gelogd of in het auditlog geschreven. Het auditlog legt vast wie de inloggegevens heeft toegevoegd, gewijzigd of verwijderd.

Ophalen via de proxy

Log in bij frem.sh met je fremforge-gebruikersnaam en een persoonlijk toegangstoken met read:package, en pull daarna met het prefix van de dependency-proxy:

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

Officiële images staan op Docker Hub onder library/, dus node:24 wordt frem.sh/<org>/dependency-proxy/docker.io/library/node:24. Andere images houden hun namespace: pgvector/pgvector:pg17 wordt frem.sh/<org>/dependency-proxy/docker.io/pgvector/pgvector:pg17.

Je kunt ook op digest pullen, en een vastgepinde digest voor meerdere platforms werkt ongewijzigd:

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

In Forgejo Actions

Een job kan inloggen met zijn eigen job-token. Hij haalt alleen op via de dependency-proxy van de organisatie van zijn eigen repository.

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 .

Staan de FROM-regels van de Dockerfile op het prefix frem.sh/<org>/dependency-proxy/docker.io/, dan haalt de build met die login via de proxy op.

Een job die door een pull request vanuit een fork wordt gestart, draait nooit met de inloggegevens van je organisatie, en kan docker.io-images dus niet via de proxy ophalen. Haal die rechtstreeks van Docker Hub.

Zonder inloggegevens

Heeft je organisatie geen ingeschakelde docker.io-inloggegevens, dan geeft een pull via de proxy 403 DENIED terug:

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

De proxy valt niet terug op een anonieme pull van Docker Hub. Sla inloggegevens op, of verwijs rechtstreeks naar het image (docker.io/...); dat is een anonieme pull onder de limiet van Docker Hub voor anonieme pulls.

Andere registries gedragen zich anders: ghcr.io en quay.io werken anoniem via de proxy als je er geen inloggegevens voor hebt, en gebruiken die van jou als je ze wel hebt.

Controleren of het werkt

• Haal een image op via de proxy en kijk daarna op de pagina Usage van je Docker Hub-account: de pull wordt daar één keer geteld. Een tweede pull van hetzelfde image komt uit de cache.
• Mislukt een pull met 503 en your organisation’s docker.io credential could not be used, dan konden de opgeslagen inloggegevens niet worden geopend. Dat is een fout aan de kant van fremforge, en die wordt gelogd.