GoDoxy: a Docker-aware reverse proxy that reads container labels

The problem GoDoxy targets: proxy config that drifts from your containers

Every self-hosted stack eventually accumulates the same chore. You add a container, then you edit a proxy config to point a hostname at it, then you reload the proxy. The proxy's view of the world and Docker's view of the world are maintained separately, so they drift. GoDoxy inverts that. The README describes the loop plainly: list all the containers, read container name, labels, and port configurations for each of them, create a route if applicable, then watch for container and config changes and update automatically. A route is described in the README as analogous to a Virtual Host in NPM. The audience is the self-hoster running a handful to a few dozen services on one or more Docker hosts, who wants the proxy to follow the containers rather than the other way round. The subdomain comes from the label proxy.aliases, and if that label is unset it falls back to the container_name field in docker compose. The README's example is a container labelled proxy.aliases: qbt, reachable at qbt.domain.com.

Discovery, labels and the host network requirement

The mechanism is label-driven discovery plus a watch loop. GoDoxy reads Docker and Podman containers, derives routes, and hot-reloads on container state changes. Configuration can live in Docker labels or in route files, and the folder layout in the README shows both: a config/config.yml, a config/middlewares directory of per-middleware YAML files, and provider files such as provider1.yml. The design constraint that shapes everything else is networking. The README states that GoDoxy is designed to be running in host network mode and instructs you not to change it, with listening ports changed through .env instead. That is not a stylistic preference. Route binding to Proxmox nodes and LXC containers depends on reaching them by hostname or IP, and the README's reverse lookup rules match a route to a node when hostname, IP or alias matches a Proxmox node name or IP, or to a container when it matches an LXC container. Running the proxy inside a bridge network would put it behind a layer of NAT relative to those targets. The setup also expects wildcard DNS pointing at the machine, an A record such as *.domain.com to 10.0.10.1, and optionally an AAAA record for IPv6.

Getting it running: setup script, compose, and the manual path

The quick start is three steps. Create a directory for the compose file and config, run the setup script from inside it, then start the service. The script is fetched and executed in one line: /bin/sh -c "$(curl -fsSL https://raw.githubusercontent.com/yusing/godoxy/main/scripts/setup.sh)". After that, docker compose up -d from the generated compose.yml, and the WebUI answers at https://godoxy.yourdomain.com. If you would rather not pipe a remote script into a shell, the README documents a manual route with three wget commands: one for config.example.yml into config/config.yml after mkdir -p config, one for .env.example into .env, and one for compose.example.yml into compose.yml. The resulting tree holds certs, compose.yml, config with config.yml, middlewares and provider files, data/metrics with uptime.json and system_info.json, and .env. There is also an agent installer script with update and uninstall subcommands, and the README says it supports both systemd and Alpine/OpenRC hosts via rc-service. Building from source needs Go 1.22 or newer plus a tool called shadowtree, with shadowtree mod-tidy for dependencies and shadowtree build for the binary. Note that shadowtree is a separate repository by the same author, so the build path depends on a second project.

Where the feature list stops being a proxy

GoDoxy's feature list goes well past HTTP forwarding. On the traffic side: HTTP reverse proxy, TCP and UDP port forwarding, OpenID Connect SSO, ForwardAuth integration (the README names TinyAuth), HTTP middlewares, and custom error pages. On access control: IP and CIDR rules, country and timezone rules requiring a MaxMind account, access logging, and periodic access summaries. Idle sleep stops and wakes Docker containers based on traffic, and does the same for Proxmox LXC containers. The Proxmox integration also binds routes to nodes or LXC containers, starts, stops and restarts LXC containers from the WebUI, and streams node and LXC logs over WebSocket. Metrics and logs are surfaced in the UI. That breadth is the honest selling point and also the honest risk: a proxy that can stop your containers is a proxy whose bugs have a larger blast radius than a proxy that only returns 502. The country and timezone rules add a MaxMind account as an external dependency, and the Proxmox features require a Proxmox host to be useful at all. If your setup is one Docker host and five services, most of this is dead weight.

Limitations: platform support, licence, and the host-mode constraint

Three constraints are visible in the material. First, platform support is listed as Linux amd64 and Linux arm64, nothing else. Second, the repository's licence is reported as NOASSERTION, which means GitHub could not map the LICENSE file to a known identifier. The README does not state a licence, so anyone who needs to know the terms of redistribution or commercial use has to open the LICENSE file directly. I cannot tell you what it says. Third, the host network requirement rules out deployments where the proxy must sit in its own network namespace, and it means port conflicts with anything else on the host are your problem to resolve through .env. There is a fourth, softer limitation: the project leans on external services and accounts. Let's Encrypt certificates come through DNS-01 providers, so your DNS host must be among the documented providers. Geo rules need MaxMind. The documentation lives on a separate site, docs.godoxy.dev, and the README points to a ChatGPT assistant for questions, which tells you something about the volume of support questions relative to written docs.

How this differs from Traefik and Caddy

Traefik is the closest comparison because it also discovers Docker containers and reads labels. The difference in approach is scope and configuration surface. Traefik exposes a provider and middleware model where routing rules are expressed as label expressions and middlewares are declared as separate objects, and it is designed to run in many topologies including Kubernetes. GoDoxy instead treats the container name as the default hostname, adds Proxmox LXC lifecycle control and idle sleep as first-class features, and ships a WebUI for editing routes, config, containers, logs, metrics and uptime. Caddy takes a different route again: a Caddyfile or JSON config with automatic HTTPS, and container awareness only through plugins or a separate generator. If you want a proxy that stays a proxy and composes with other tools, Caddy or Traefik will feel less opinionated. If you want one binary that also stops idle containers and restarts your LXC boxes from a browser, GoDoxy is doing something the others do not attempt in the same package.

Maintenance cost and what to check before you commit

The release cadence visible in the material is roughly weekly: v0.31.0 on 2026-08-21, v0.31.1 on 2026-08-28, v0.31.2 on 2026-09-10. That is a fast-moving 0.x project, and the version numbering says the author has not declared the config format stable. Expect to read release notes before upgrading, and expect that a config key you rely on may move. The agent installer has an explicit update subcommand, which suggests in-place upgrades are the expected path rather than rebuilds. On licence: because the licence is unresolved in the repository metadata, treat redistribution and commercial embedding as unverified until you read the LICENSE file, and I am not in a position to give legal advice on what it permits. The concrete things to verify first are the LICENSE file, whether your DNS provider appears in the DNS-01 provider list, and whether you can run the container in host network mode. If any of those three fails, the setup path in the README does not apply to you as written.

Editorial conclusion

GoDoxy suits self-hosters already running Docker in host network mode who want routes derived from container labels instead of hand-edited vhost files, and who accept a single-maintainer project with an unresolved licence. It is the wrong pick if you cannot use host networking, need a large plugin ecosystem, or require a permissive, clearly identified licence for redistribution. Before adopting, read the LICENSE file in the repository, confirm the DNS-01 provider you use appears in the documented provider list, and check that your host kernel and architecture match the two supported platforms, Linux amd64 and Linux arm64.

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. yusing/godoxy on GitHub