Installing when registry.docker.com is not available: using registry-mirror in docker daemon config

[syn]

When running a normal ./cloudron-setup in a restricted network environment or during a docker hub outage:

2026-06-21T09:58:41 ==> installer: downloading new addon images
2026-06-21T09:58:41 ==> installer:      Pulling docker images: registry.docker.com/cloudron/graphite:3.5.3@sha256:44ddbfd8c30d3eaa4fa6db207f4e18a4f1749ce6ed82d44e9e9a233a96febced registry.docker.com/cloudron/mail:3.18.2@sha256:130d518db6d56aa536f19a4901d7bc265666927165205aed302e6450c51791c7 registry.docker.com/cloudron/mongodb:6.3.0@sha256:8757111970a99fb9a9880f02a2a77fe9cb7368745fcff555bf528471ecb50ec3 registry.docker.com/cloudron/mysql:3.6.0@sha256:12fd9d8d92a41b78ca422ef05d7dade75eba4f8647b0fabaa873ba6efb607783 registry.docker.com/cloudron/postgresql:6.4.0@sha256:759c5c68e8f3a91592911177dcd2e9e39de48528b7b1bab659bae2f5ebd2d207 registry.docker.com/cloudron/redis:3.8.0@sha256:54a12252edbc326fd4d10e8c00836cc68776f3463f22366279f7cd8d4dafd20f registry.docker.com/cloudron/sftp:3.10.0@sha256:c3a65928ef5cf7ba0750e93d9c605fb39e7fec02de7db05cffe80927b39943de registry.docker.com/cloudron/turn:1.8.2@sha256:9f3609969a5757837505c584c98246a3035a84a273b9be491665ac026423fd5f
Error response from daemon: Get "https://registry.ipv4.docker.com/v2/": net/http: TLS handshake timeout

I configured the mirror via /etc/docker/daemon.json with e.g {"registry-mirrors": ["https://mirror.gcr.io"]}

But currently cloudron uses registry.docker.com as an explicit registry host, so it bypasses the Docker Hub mirror registry config.

Patching src/infra_version.js to replace registry.docker.com with docker.io enables the proxying.

The ipv6 workaround implemented in or after https://forum.cloudron.io/topic/7420/ipv6-only-cloudron would also need to be patched, but otherwise this seems a net win?

[girish]

Right, explicit registry.docker.com was added for better IPv6 support. So, mirror.gcr.io is mirroring all of docker hub? Where can I find more information ?

[syn]

https://docs.cloud.google.com/artifact-registry/docs/pull-cached-dockerhub-images

[syn]

as for registry.docker.com vs docker.io: i got that from LLM and confirmed this was the case while installing. As soon as I patched infra_version.js - docker daemon stopped trying that explicit docker registry and fell back docker.io to the configured mirror

[girish]

The docker code uses dockerode (node module) as the client. Since the option is in daemon.json, I imagine registry-mirrors is a feature of the docker daemon though and not the client Have to really investigate.

https://docs.cloud.google.com/artifact-registry/docs/pull-cached-dockerhub-images

It does say that it caches "popular" images, not sure what that means.

For our apps, we already use quay.io as the fallback. We push images to both docker hub and quay. Maybe that is what we need to do for the platform images.

[syn]

If the image still isn't found, the Docker daemon fetches the image from the canonical repository on Docker Hub.
that's a feature of docker daemon itself. Fallback through the list of configured registry-mirrors.

The key here is that docker pull docker.io/cloudron/base is treated exactly as "docker pull cloudron/base" (implicit hub.docker.com) whereas docker pull registry.docker.com/cloudron/base is ignoring registry-mirror list because it is an explicit registry image ref.

quay.io would also fail in a "restricted" network environment.

One of the other solutions I considered is to allow a "cloudron base registry" option in the installer.