POC of rate-limit relief of Docker Hub Pull

This is a Proof-Of-Concept compose stack to deploy a local docker registry that

1. Does Single User Authentication

• As I am the only user

2. Reflief Docker Pull Rate Limit

• By acting a pull through proxy cache, to serve image already downloaded
• By rotating VPN connection (I use Surfshark as the VPN provider, you may change the code for other provider) when the usage is over a certain percentage

3. Access the local registry from internet using cloudflare tunnel, with simple authentication This registry is just a prototype of that POC to fit my requirements.

How this works

1. qmcgaw/gluetun is the VPN container that routes through the traffic to registry-1.docker.io

• The setup can be referred to here
• The update API can be found on this issue, I use different paramenters to call that fit my needs of down to a specific hostname update.

2. cloudflare/cloudflared act as a tunnel and HTTPS endpoint to expose the registry to internet (and you need to set http://gluetun:5000 on your ZeroTrust)

• You can also expose it through like Pangolin / Tailscale Funnel, Cloudflare tunnel is just personal perference

3. library/registry as the actual registry
4. docker-rate-limit-cron should be compiled, this will check the limit threshold of the pull limit and trigger a VPN change request to the gluetun

• The rate limit check by docker official can be referred here

Configuration

1. rate-limit-checker-config.json, used in docker-rate-limit-cron to control

• Threshold of the limit and checking frequency
• List of VPN to rotate (I specify the list as I want faster server specified)

2. gluetun-config.toml

• This is to expose an API to update the VPN host, don't change that unless you need more control (and you need to change the docker-rate-limit-cron)

3. htaccess The configuration is to authenticate the user for docker login, example has a username/password as: USERNAME/PASSWORD please use htpasswd -bnBC 10 USERNAME PASSWORD to generate a nmew user line and paste your config here

Effect

After setting the ZeroTust Tunnel config to http://gluetun:5000, and run a docker compose up, a rate-limit relief caching registry is available to access through internet.
You can pull that by specifying the pull-through cache

docker pull your.registry.domain.com/library/traefik:latest

And once the limit is busted, the checker will rotate the VPN, creating a semi automatic rate-limit reflief registry.

rl-cron-1         | [2025-06-09T14:22:59.212Z] Used pull for (118.xxx.xxx.xxx): 2 / 100 (2%)
rl-cron-1         | ⚠️  Rate limit below 99%. Changing VPN to: jp-tok-st015.prod.surfshark.com
rl-cron-1         | [2025-06-09T14:23:09.407Z] Used pull for (138.xxx.xxx.xxx): 0 / 100 (0%)