Docker Registry v3 not compatible with current documentation #3198
Description
Hi! I was migrating my GitLab Instance to new hardware in the last days and I've run into a point that probably needs clarification in the documentation (or at least an issue here to be found by fellow sufferers).
In https://github.com/sameersbn/docker-gitlab/blob/master/docs/container_registry.md, the example shows a compose.yaml with image: registry, which is using latest (= 3.0.0 at the moment)
However, with the self-signed certificate described in the same documentation, I could not get Registry v3 to work. I analyzed the generated JWT auth tokens and they were 100% valid, however the docker registry always refused to use them.
registry-1 | time="2026-01-05T11:56:30.161362114Z" level=info msg="failed to verify token: token signed by untrusted key with ID: \"B4PU:UVYR:MXU3:27NL:IYBX:VSLM:YOSS:6JLL:MWCM:BTAU:EHJT:LDG5\""
registry-1 | time="2026-01-05T11:56:30.161391381Z" level=warning msg="error authorizing context: invalid token" environment=production go.version=go1.23.7 http.request.host=registry.nrausch.dev http.request.id=e7a1d42e-aff5-4514-a6b3-f23503a4ad7e http.request.method=GET http.request.remoteaddr=[redacted] http.request.uri=/v2/ http.request.useragent="docker/28.0.4 go/go1.23.7 git-commit/6430e49 kernel/6.8.0-88-generic os/linux arch/amd64 UpstreamClient(Docker-Client/28.0.4 \\(linux\\))" instance.id=d28b9430-5d29-4eb2-9537-61f0b9f67f9a service=registry version=3.0.0
ROOTCERTBUNDLE was correctly set and I tried with multiple different certificates, with/out CA flag, with/out alt names, etc.
Today out of curiosity i checked the logs of my old server and saw that registy:latest resolved to 2.8.3 there - downgraded to 2.8.3 and it worked instantly.
Today I found this issue stating that v3 additionally needs a JWKS file (REGISTRY_AUTH_TOKEN_JWKS) to accept the GitLab JWTs. Using this option, I could now switch to registry:3.0.
I'd suggest adding a short note to the container_registry docs that either registry:2 should be used or an additional JWKS file must be generated in order to run the newer version. Ideally, the startup logic should be adapted to generate a JWKS file alongside the key and certificate.