GoDoxy installs by piping a setup script into /bin/sh, then insists on host networking
High-performance reverse proxy and container orchestrator for self-hosters
At a glance
- What is it?
- GoDoxy is a reverse proxy that discovers Docker and Podman containers and turns their labels into routes, with a WebUI, Let's Encrypt through DNS-01, Proxmox integration and idle sleep. The deployment story is the interesting part. The quick start pipes a remote script into a shell, the compose example reaches Docker through a loopback TCP proxy rather than the socket, the environment file carries three generations of variable names, and the manifest asks for a newer Go than the build instructions do.
- Who is it for?
- GoDoxy fits a homelab where services come and go as containers and you do not want to hand-edit a proxy configuration every time one appears, since route discovery from labels plus hot reload removes that work, and the WebUI covers the rest. Two things to settle before you point it at anything.
- Can I use it commercially?
- Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
- Is it still maintained?
- Yes. The repository last received commits 9 days ago.
- What is it written in?
- Mainly Go, 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.
Star history
- yusing/godoxy4,189 ★ · +42
| Repository | 2026-09-11 | 2026-11-15 |
|---|---|---|
| yusing/godoxy | 4.1k | 4.2k |
42 Stars in the last 65 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The quick start pipes a remote script into a shell, in host network mode
The documented path starts with DNS and ends with a shell command that downloads and executes a script. Wildcard records are needed first: an A record pointing a subdomain wildcard at the machine's address, and an AAAA record for IPv6, whose example value is an IPv4-mapped IPv6 address written in full. Then a new directory is prepared for the compose and config files, and the setup script is run inside it:
/bin/sh -c "$(curl -fsSL https://raw.githubusercontent.com/yusing/godoxy/main/scripts/setup.sh)"which generates a compose file, after which the service starts with `docker compose up -d` and the WebUI is reached over HTTPS at a subdomain of your own domain.
Two constraints sit in a note above that sequence, and both matter. GoDoxy is designed to run in host network mode and the note says not to change it, which means the container shares the host's network namespace and therefore the host's ports. Listening ports are changed by editing the environment file, not by any network setting. Anyone running this alongside something else that binds port 80 or 443 needs to know that before they start.
The Docker endpoint is reached through a loopback proxy on port 2375
The compose example does not hand the container the Docker socket. Instead there is a socket proxy in the tree, and the environment file describes the arrangement: the host socket path is a variable, with the Podman socket named as the alternative, and the proxy's own listener is set to loopback on port 2375. A comment states that the Docker host variable must stay pointed at that address for this setup, and that Compose reads the value from the environment file without rewriting it.
That is the correct pattern for a container that needs to create other containers, and it is worth understanding why. Mounting the raw socket gives whatever holds it full control of the Docker daemon. A proxy that listens on loopback still does, but it is one address you can bind and firewall rather than a filesystem object passed into every container.
The catch is that it is still an unauthenticated daemon endpoint on a TCP port. The environment file also carries a user and group id that must own the mounted directories, which tells you the container runs as a non-root user with a fixed identity rather than as root.
Three generations of variable names, and HTTPS_ADDR is the exception
The example environment file is generated, and its header says not to edit it. The names it documents reveal how the project has been renamed over time. There are three tiers: the current prefix, a legacy prefix inherited from the project's earlier name, and unprefixed names marked deprecated. The rule is that the first non-empty value wins, in that order, and the file tells you to rename old settings to the current prefix.
There is one deliberate exception, and it is the kind of detail that causes incidents. The HTTPS listener variable behaves differently: the first variable that is set wins, even if it is empty, and an empty value turns off shared HTTPS entirely, including shared HTTP/3 and TCP routing by SNI. A configuration that looks like it disables something may instead be enabling it for every legacy name still present in the file.
The rest of the file separates compose inputs from server settings. Compose inputs keep their exact names because Compose reads them directly: an image tag, a timezone for log timestamps, the user and group ids, the socket path, and the proxy listener address. Server settings are prefixed and documented with their defaults commented out, covering the HTTP listener, the HTTPS listener, an HTTP/3 switch that does not apply when the PROXY protocol is in use, and a switch for routing TCP over the shared HTTPS listener by TLS SNI.
go.mod asks for Go 1.27; the build instructions say 1.22 or newer
The build-from-source section and the module file disagree, and the difference is large. The instructions say to install or upgrade Go 1.22 or newer, and add a step telling you to clear the build cache if you built the project before with a version below 1.22. The module file declares 1.27.0, and the container build starts from that exact Go release on Alpine.
So the 1.22 figure is a floor from an earlier era rather than what the code now needs. Following the instructions literally on a 1.22 toolchain will not produce a working binary.
The rest of the build is unusual in a way worth knowing. The clone is shallow. Dependencies are not fetched with the standard tool: the instructions say to install a separate program written by the same author and run its dependency command, then its build command. That program is what the container image installs at build time as well, pinned to a version argument that defaults to the latest, with the Go build cache and module cache both mounted as build caches.
The manual setup path, for people who would rather not run a script, is three download commands that fetch the example configuration, the example environment file and the example compose file into place, followed by a documented directory layout with certificates, config, middleware files, provider files and a metrics directory holding uptime and system information data.
Ten replace directives point at local copies of two upstream libraries
The module file contains a replace block with ten entries, and only two of them are third-party forks. An OIDC authentication library is redirected to a directory under `internal/`, and a process and system utilities library is redirected to another internal directory. The other eight point at the project's own submodules: the agent, an internal DNS provider module, and six paths inside a shared utilities tree covering a cache, an HTTP reverse proxy, a WebSocket package and a server package.
Forking the OIDC library is the decision with the widest consequences, since single sign-on is a documented feature and the vendored copy is what implements it. Forking the system utilities library means process and host metrics come from local code rather than the upstream release.
The rest of the dependency list is annotated in the module file, which makes it unusually readable. An HTML parser is there for extracting favicons and for a middleware that rewrites HTML, a hashing library is used for a fast 64-bit hash, a backoff library for retries, a glob matcher for route rules, a YAML library for parsing several different configuration files, a validator, a JWT library, a WebSocket library for the API and the agent, and an ACME client for certificate issuance. A file-change watcher provides the hot reload. A comment next to one of them explains that the Docker command library is required specifically for a connection helper that the Docker client needs.
One exclusion, with a precise reason about an empty subname
There is a single exclude directive in the module file, and the comment above it is the most useful sentence in the file for anyone debugging a DNS provider. A DNS provider library at version 0.11.2 is excluded because that version encodes an empty subname as JSON during a patch request, and the provider rejects it, since the field is create-only.
That is a small bug with a large blast radius if you hit it: certificate issuance for one provider silently failing while every other provider works, and the failure surfacing as a rejected request rather than as a parse error. Writing the reason next to the pin is the difference between a five-minute fix and an afternoon.
It also tells you something about how the project handles dependencies generally. Versions are exact rather than ranged, the two forked libraries are tracked as directories inside the repository, and the module file carries a comment beside almost every requirement explaining what it is for. That is a dependency list maintained by hand with reasons attached, which is more work than most projects do and more useful when something breaks.
Two SonarCloud project ids, three CI configurations, and a chat bot as support
A few things in the repository do not line up, and they are all small. The readme carries two SonarCloud badges for new code with different project identifiers, one under the project's current name and one under an older one, which usually means analysis is running against one project while the badge reads the other.
Continuous integration is configured three times over: a GitHub workflows directory, a GitLab CI file, and a Jenkinsfile at the root. Linting is configured twice as well, with a Go linter configuration and a separate trunk directory, so there are two tools policing the same tree.
The support entry point is unusual. Alongside the documentation site and the Discord server, the readme offers a link to a purpose-built chat assistant, credited to another user, and links a running demo instance. Whether that is a good idea for a project whose audience is homelab operators with credentials to configure is a question the project has answered for itself.
The rest of the tree is well organised for its size: an agent directory, a command directory, internal and package trees, a socket proxy, end-to-end tests, a development Dockerfile and compose file, separate examples for routes, error pages and a dashboard template, screenshots, a second Go module for shared utilities with its own manifest, and rootless variants of both the compose file and the environment file.
Editorial conclusion
GoDoxy fits a homelab where services come and go as containers and you do not want to hand-edit a proxy configuration every time one appears, since route discovery from labels plus hot reload removes that work, and the WebUI covers the rest. Two things to settle before you point it at anything. Host networking is described as required and not to be changed, which means the proxy shares the host's network namespace and its listening ports, so decide what else runs on those ports first. And the compose example exposes the Docker endpoint over a loopback TCP proxy rather than the raw socket, which is the right pattern, but it also means anything that can reach that port can control containers, so keep it on loopback and do not widen it.
Frequently asked questions
What is GoDoxy?
GoDoxy is a reverse proxy written in Go with a Web interface, described as lightweight and aimed at self-hosters. It lists Docker and Podman containers, reads their names, labels and port configuration, creates a route for each one that qualifies, and watches for container or configuration changes so routes update themselves. Documentation is at docs.godoxy.dev and a demo instance is published.
How does GoDoxy map a container to a hostname?
Through the label `proxy.aliases`, which supplies the subdomain or subdomains. If that label is unset it falls back to the container name field from your compose file, so a container labelled with the alias `qbt` is reachable at `qbt` followed by your domain.
How do I install GoDoxy?
Point a wildcard DNS record at the machine, prepare a directory, and run the setup script from the repository, which generates a compose file, then start it with `docker compose up -d`. A manual path downloads the example configuration, the example environment file and the example compose file into place. The readme states that the service is designed to run in host network mode and should not be changed, with ports configured in the environment file.
Does GoDoxy work with Podman or rootless Docker?
Container discovery covers both Docker and Podman, and the environment file names the Podman socket path as the alternative to the Docker one. The tree also carries a rootless compose example and a rootless environment example. Supported platforms are listed as Linux on amd64 and Linux on arm64.
Can I use Nginx as a proxy in Docker?
The repository does not mention Nginx. What it describes is its own routing model, where routes come from container labels or route files rather than from a hand-written configuration, and are described as comparable to a virtual host in another proxy. The comparison appears in the explanation of how a route is created once a container qualifies.
What certificates does GoDoxy handle?
Let's Encrypt certificates obtained through DNS-01 challenges with configurable providers, alongside HTTP reverse proxying, TCP and UDP port forwarding, OpenID Connect single sign-on, ForwardAuth integration, HTTP middlewares and custom error pages. Access control adds IP and CIDR rules plus country and timezone rules that require a MaxMind account.
Official sources
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.
[](https://hysenlabs.com/projects/yusing-godoxy)Star history chart for your README
[](https://hysenlabs.com/projects/yusing-godoxy)Was this useful?