Self-hosted service
dqzboy/Docker-Proxy avatar
dqzboy/Docker-Proxy

dqzboy/Docker-Proxy: a zero-disk pull accelerator with a web panel

Self-hosted Docker image acceleration and management service. Zero disk caching, a visual dashboard, upstream account authentication, and one-click accelerated deployment for Docker, K8s, Quay, GHCR, MCR, Elastic, NVCR and other registries.

4,460 stars610 forksJavaScriptApache-2.0

At a glance

What is it?
A Go proxy that sits in front of Docker Hub, GHCR, Quay, K8s, MCR, Elastic and NVCR, streams layers through without caching them to disk, and hands configuration to a browser panel instead of a hand-edited YAML file. Useful on a single overseas host, awkward for anyone who needs image caching.
Who is it for?
Adopt it if you run one or two servers outside your home region, pull from Docker Hub and private GHCR or Quay images, and would rather edit registries in a browser than in a mounted config.yaml. Do not adopt it if you need cached layers on a repeated build, if your CI has to work with the upstream disconnected, or if you need per-user registry accounts rather than a single upstream login and an IP allowlist.
Can I use it commercially?
Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 5 days ago.
What is it written in?
Mainly JavaScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • dqzboy/Docker-Proxy4,460 ★ · +46
Star history
Repository2026-09-232026-11-15
dqzboy/Docker-Proxy4.4k4.5k

46 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

One process routes by Host and streams layers through without writing them

The whole idea is that nothing is stored. A single Go process sits between your Docker daemon and the public registries, looks at the Host header of each request, picks the matching upstream, performs the token exchange, and passes the layer bytes along as they arrive. No blob is written to the host filesystem, so there is no cache directory to size, no eviction policy to reason about, and no disk fill-up alert at 3am.

That choice also removes the feature that makes most pull-through caches attractive. Because nothing is kept locally, the second pull of the same image goes back out to the upstream. The compose file notes that the default configuration sets cache.enabled=false, and the compose file mounts ./data/go-proxy-cache at /app/cache purely as the place a cache would land once you turn it on.

Who this suits is narrow: a developer or a small team with a handful of servers in one overseas location who wants Docker Hub pulls to take a shorter path and wants to set that up without hand-editing a reverse proxy config.

Host-based routing across Docker Hub, GHCR, Quay and NVCR

Routing is automatic once you point at the proxy, because dispatch is driven by the registry host in the request rather than by a path prefix you have to rewrite. Docker Hub, GHCR, Quay, K8s, MCR, Elastic and NVCR are named as the upstream set, and the panel lets you add, edit and delete registry entries per registry without touching files.

Token handling happens server side. With upstream credentials configured, the proxy exchanges them for a Bearer Token itself, which is what lets it pull private Docker Hub images on your behalf and eases the rate limiting that anonymous Docker Hub pulls hit.

Access control sits at the same layer. An IP allowlist and denylist accept single addresses and CIDR ranges, so you can decide which clients are allowed to pull through the service at all. That is the one place where the design has a real opinion: the proxy is meant to be reachable, so the guard is network identity, not per-user credentials.

Bringing it up with docker compose and opening the panel on port 30080

The shortest path is the compose file in the repository root. It starts two containers on a shared network named registry-net: the Go proxy and the hubcmd-ui panel, which depends on go-proxy.

bash
docker compose up -d

After the containers start, open the panel at http://<server IP>:30080/admin. That is the UI container's port mapping, not the proxy's. The panel is where you add registry proxies, set server parameters, watch resource and traffic dashboards, and trigger a hot reload.

If you would rather have the script handle dependencies, the repository ships install/DockerProxy_Install.sh, which installs Docker and Compose if missing, generates a random GO_PROXY_ADMIN_TOKEN into .env, and optionally renders an Nginx or Caddy reverse proxy in front of the service.

bash
bash -c "$(curl -fsSL https://raw.githubusercontent.com/dqzboy/Docker-Proxy/main/install/DockerProxy_Install.sh)"

Run it on a host outside your home region. The README states that the domain does not need mainland China ICP filing, and that choosing Caddy in the one-click script configures HTTPS automatically.

The startup check that refuses to boot on a placeholder admin token

GO_PROXY_ADMIN_TOKEN is not decorative. The proxy validates it at startup and exits rather than come up on a weak value: a placeholder such as change-me or admin, an empty string, or anything shorter than 16 characters is rejected outright. For local development of the go-proxy subproject the README gives the exact command to satisfy it.

bash
export GO_PROXY_ADMIN_TOKEN="$(openssl rand -hex 16)"

This check matters because the admin API is a separate surface from the registry path. Port 5000 is the OCI registry reverse proxy and is meant to face the reverse proxy or the internet. Port 5001 carries /-/healthz, /-/config, /-/reload, /-/stats and /-/credentials, and the README marks it internal only. That API can rewrite the running configuration and read stored upstream credentials, so leaving it published is a much worse mistake than leaving 5000 open, which is the entire point of the service.

SESSION_SECRET plays the same role for the panel's session cookies. The .env.example file ships it as the placeholder change-me-to-a-strong-random-secret and tells you to generate one with openssl rand -hex 32; rotating it invalidates every existing login session, which is worth knowing before you rotate it during an incident.

The compose file publishes 50000 and 30080 but never 5001

Look at the port mappings and one detail jumps out. The go-proxy service maps 50000:5000, so the registry path is exposed on a high host port rather than on 5000 itself. The hubcmd-ui service maps 30080:3000. Nowhere in the compose file is 5001 published.

That is a deliberate boundary, and the two services still reach it because they share registry-net. The UI is pointed at the admin port with GO_PROXY_ADMIN_URL=http://go-proxy:5001 and carries the same GO_PROXY_ADMIN_TOKEN. If you add an entry to ports so you can curl /-/healthz from your laptop, you are undoing a separation the file already got right.

A second detail sits in the volume mounts. The host directory ./config/go-proxy is mounted at /app/config.d, where the config lives at config.yaml inside the container. On first start, if the host has no config file, the container seeds one from the defaults baked into the image. Recovery from a bad edit is therefore a file deletion: remove ./config/go-proxy/config.yaml, recreate the container, and the defaults come back.

root / admin@123 ships beside a startup check that bans placeholders

Here is the contradiction worth pausing on. The Go service refuses to start on a weak GO_PROXY_ADMIN_TOKEN, length under 16 or a known placeholder, yet the HubCMD-UI panel logs you in as root with the password admin@123 out of the box. The README repeats the pair twice, in the panel section and again in the local development section, first with an instruction to change it after deployment and then with a note that the first login prompts a password change.

The mismatch is in the security model rather than in the code. The token guards a machine-to-machine API between two containers on a private network. The panel password guards a human-facing login form exposed on 30080. A strict check on the first and a fixed default on the second means the weaker of the two doors is the one you must remember to close.

Treat admin@123 as a value that exists in public documentation, not as a starting password. Change it at first login, which the panel also prompts for.

Where this differs from daemon.json registry-mirrors and from Caddy routing

The built-in answer to slow Docker Hub pulls is the registry-mirrors array in /etc/docker/daemon.json: point the daemon at a mirror and it retries pulls against it. That approach needs no process of your own, no admin token and no panel, and the daemon decides which mirror to fall back to. Docker-Proxy takes the opposite position. It terminates the OCI registry protocol itself, authenticates to upstreams, and hands every registry its own configuration through a browser UI, which is why it needs port 5001 and a signed session secret at all.

Caddy with caddy-docker-proxy solves a different layer again: it discovers containers from the Docker socket and routes HTTP traffic to them automatically. Docker-Proxy never inspects /var/run/docker.sock for routing decisions; the UI container mounts that socket for container management, while the proxy routes by registry Host. Choose the mirror approach for pull performance on a handful of hosts. Choose this one when you also want private upstream credentials, per-registry settings, IP allowlists, and traffic alerts on the same box. Skip it if you wanted layer caching, since the default is to stream everything and reach upstream again on the next pull.

The repository is not archived, its last push was on 2026-10-21 with release v5.1.9 dated 2026-09-22, and it ships under Apache-2.0.

Editorial conclusion

Adopt it if you run one or two servers outside your home region, pull from Docker Hub and private GHCR or Quay images, and would rather edit registries in a browser than in a mounted config.yaml. Do not adopt it if you need cached layers on a repeated build, if your CI has to work with the upstream disconnected, or if you need per-user registry accounts rather than a single upstream login and an IP allowlist. Verify three things before the first deploy: change the shipped root / admin@123 panel login, confirm that port 5001 stays off the ports list in docker-compose.yaml so /-/credentials and /-/reload are not reachable from outside registry-net, and set SESSION_SECRET with openssl rand -hex 32 instead of leaving the placeholder in .env.example.

Frequently asked questions

What is docker-proxy?

In this repository, docker-proxy is a self-hosted image acceleration service that routes by Host to Docker Hub, GHCR, Quay, K8s, MCR, Elastic and NVCR, completes token authentication server side and streams layers through without writing them to disk.

How do I set up docker-proxy?

Download docker-compose.yaml from the repository root and run docker compose up -d, or run install/DockerProxy_Install.sh, an interactive menu that installs Docker and Compose, generates a random GO_PROXY_ADMIN_TOKEN into .env, and can render an Nginx or Caddy reverse proxy. After startup the panel is reachable at http://<server IP>:30080/admin.

How do I use docker proxy?

Point your Docker daemon at the proxy's published registry port and manage everything else from the HubCMD-UI panel at /admin, where you add or edit registry proxies, set server parameters and trigger a hot reload. The go-proxy backend also exposes an admin API on port 5001 with endpoints including /-/config, /-/reload and /-/stats, which is documented as internal only.

Official sources

  1. dqzboy/Docker-Proxy on GitHub
  2. License: Apache-2.0
  3. Project website
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/dqzboy-docker-proxy.svg)](https://hysenlabs.com/projects/dqzboy-docker-proxy)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/dqzboy-docker-proxy.svg)](https://hysenlabs.com/projects/dqzboy-docker-proxy)

Was this useful?