Self-Host GoDoxy on Linux with Localtonet

What this tutorial verifies, and what remains deployment-specific

GoDoxy and Localtonet address different layers of a remote-access design. GoDoxy runs on a Linux host and acts as a reverse proxy and container orchestrator. According to the current official GoDoxy repository, it can discover Docker and Podman containers, create routes from container metadata, reload configuration when containers or files change, manage certificates, proxy HTTP traffic, forward TCP or UDP traffic, and provide a management WebUI.

Localtonet provides the connectivity layer. Our client runs on a device that can reach a local service and establishes an outbound connection to a Localtonet relay. An HTTP tunnel can provide a public HTTPS address for a selected local HTTP endpoint without requiring an inbound router port forward, a public IP address, firewall changes for unsolicited inbound internet traffic, or a VPN setup. Creating a tunnel does not start it, and the public route is available only while the selected client is connected and the tunnel is running.

Those capabilities do not, by themselves, prove that a generated Localtonet hostname can be sent directly to the GoDoxy WebUI. GoDoxy commonly chooses a route using the requested hostname. An HTTPS upstream can also require a particular TLS server name and a certificate valid for that name. The available Localtonet evidence does not document a universal Host-header rewrite or upstream TLS server-name override that would make an arbitrary generated public hostname match a GoDoxy route.

A reproducible direct integration would need to establish all of the following as one tested topology:

• The public hostname used by the browser.
• The hostname Localtonet forwards in the HTTP Host header.
• Whether the local target uses HTTP or HTTPS.
• The TLS server name sent when Localtonet connects to an HTTPS upstream.
• The hostname configured on the GoDoxy WebUI route.
• Which component owns the browser-facing certificate.
• Which component owns any certificate used on the local upstream connection.
• The exact DNS records required for a Localtonet custom domain.
• The authentication or access-control policy protecting the GoDoxy WebUI.

Until current documentation or an editor-approved test confirms those details, the safe result is a locally working GoDoxy installation plus a documented integration boundary. The GoDoxy documentation and the current Localtonet HTTP tunnel documentation should be checked again at publication and deployment time because generated examples and dashboard options can change.

Prerequisites for installing GoDoxy on Linux

The current GoDoxy repository lists Linux amd64 and Linux arm64 as supported platforms. This tutorial uses Docker Compose because the upstream quick start and manual installation instructions both provide a Compose-based deployment. Recheck the live repository before publication or installation because the setup script, Compose example, environment example, configuration example, image references, mounts, and generated paths can change on the main branch.

Prepare the following:

• A Linux host using the amd64 or arm64 architecture.
• Administrative access sufficient to install and operate Docker.
• Docker Engine and the modern docker compose plugin.
• curl for the quick setup script, or wget for the documented manual file downloads.
• A dedicated deployment directory for Compose and persistent GoDoxy files.
• A domain whose DNS records you can control if you plan to use normal hostname-based GoDoxy routes.
• A backup destination separate from the live deployment directory.
• For Localtonet evaluation, an account and a Localtonet client on the GoDoxy host or another device that can reach its listener.

Confirm Docker and Compose

docker --version
docker compose version

Both commands should return version information. If Docker cannot be contacted, fix daemon availability and operating-system permissions before installing GoDoxy. Membership in a group that controls Docker is a privileged administrative capability, not an ordinary application permission.

Plan hostname resolution

The current GoDoxy quick start recommends wildcard DNS records pointing to the machine running GoDoxy. It gives an A record for IPv4 and an AAAA record when IPv6 is used. A wildcard can make hostnames such as app.example.com and files.example.com resolve to the same reverse proxy.

DNS does not create reachability or a route. A private address is useful only to clients that can route to that private network. A public record pointing to a private address does not make the service reachable from the internet. Likewise, an internet-routable address does not guarantee that a router or firewall will permit the connection.

GoDoxy uses the label proxy.aliases as application subdomains and falls back to the Compose container_name when that label is absent. For example, the upstream project shows that an alias of qbt can produce a route such as qbt.domain.com. The DNS record, GoDoxy route, listener, certificate, and access policy are still separate configuration elements.

Choose the installation method

Install GoDoxy with Docker Compose

The upstream quick start contains four practical actions: create and enter a new directory, run the setup script, inspect the generated deployment, and start the Compose service. Keeping these actions separate gives you a review point before the container receives access to host networking, configuration files, and any container-control interface defined by the generated Compose file.

1. Create the working directory

mkdir -p ~/godoxy
cd ~/godoxy

The location and directory name are local organizational choices. Run later Compose commands from the directory containing compose.yml so they operate on the intended project.

2. Run the upstream quick setup script

/bin/sh -c "$(curl -fsSL https://raw.githubusercontent.com/yusing/godoxy/main/scripts/setup.sh)"

3. Inspect the generated deployment

ls -la
sed -n '1,260p' compose.yml
docker compose config

If an .env file was generated, inspect it locally with a trusted editor. Do not publish it in a repository, support ticket, screenshot, or terminal transcript. GoDoxy's current quick start says listening ports are changed through .env, but the available evidence does not establish one universal WebUI port or a stable environment-variable name that can safely be copied into every deployment.

In the resolved Compose output, inspect:

• The exact GoDoxy image reference and whether it uses a fixed version, digest, or mutable tag.
• The documented host network mode.
• The host paths and named volumes used for configuration, certificates, and data.
• Any Docker socket, socket proxy, Podman socket, or other container-runtime control interface.
• Read-only versus read-write mounts.
• Environment variables and referenced files.
• Restart behavior and any elevated privileges or capabilities.

GoDoxy is designed to run in host network mode, and its repository explicitly says not to change that mode. Host networking means that the process uses the Linux host's network stack. It also means that conventional Docker ports output is not a reliable way to discover the listener.

4. Start GoDoxy

docker compose up -d
docker compose ps
docker compose logs --tail=200

A running container is only the first checkpoint. The logs must also show that GoDoxy loaded its files, initialized the required providers, and bound its listener without a port conflict or permission failure.

Manual Compose installation

The current repository also documents downloading its three example files directly:

mkdir -p ~/godoxy
cd ~/godoxy
mkdir -p config
wget https://raw.githubusercontent.com/yusing/godoxy/main/config.example.yml -O config/config.yml
wget https://raw.githubusercontent.com/yusing/godoxy/main/.env.example -O .env
wget https://raw.githubusercontent.com/yusing/godoxy/main/compose.example.yml -O compose.yml

Review and adapt the files before running:

docker compose config
docker compose up -d
docker compose ps
docker compose logs --tail=200

The documented layout can include certs, config, and data beside compose.yml and .env. The configuration tree can contain config.yml, middleware files, and provider files. The documented data tree includes metrics such as uptime.json and system_info.json. Certificate examples include cert.crt and priv.key.

Identify the listener, hostname, and WebUI route

The GoDoxy quick start shows the WebUI at a hostname following the pattern https://godoxy.yourdomain.com. That is a pattern, not a complete route configuration for your deployment. The available repository extract does not identify one universal WebUI port, a stable configuration key for the WebUI hostname, or a complete authentication block.

Use the generated files as the source of truth for the installation you actually created. Do not infer a listener from a familiar reverse-proxy port or copy settings from an older article.

Inspect the environment and configuration without publishing secrets

cd ~/godoxy
docker compose config
grep -RniE 'listen|port|webui|hostname|domain|route|tls|cert|auth|oidc|forward' .env config compose.yml 2>/dev/null

The search is a discovery aid, not a configuration generator. Read each matching value in context. Record the following for your own deployment:

• The listening address and numeric port.
• Whether the local listener expects HTTP or HTTPS.
• The exact hostname assigned to the WebUI route.
• The certificate source and names covered by the certificate.
• The access-control middleware or authentication integration applied to the route.
• The files or environment values that own each setting.

Inspect the host sockets

sudo ss -lntup

Match the socket to GoDoxy using the configured port, process information, and application logs. A loopback listener can be reached by a Localtonet client on the same host. A client on another LAN device needs a listener and firewall policy that permit that separate device to connect. Do not broaden the binding merely for convenience if same-host access is sufficient.

Confirm the route hostname

Configure DNS so the intended WebUI hostname resolves to the GoDoxy host from the clients that need local access. Then compare that hostname with the GoDoxy route visible in the WebUI, generated configuration, or logs. A wildcard DNS record may resolve the name, but it does not guarantee that GoDoxy has created the matching virtual host.

Confirm WebUI protection

GoDoxy lists OpenID Connect SSO, ForwardAuth integration, IP and CIDR access rules, and geographic controls among its features. The current evidence supplied for this revision does not include the exact schema, generated route setting, identity-provider fields, or middleware attachment procedure needed to configure a verified WebUI login.

Verify GoDoxy locally before considering a tunnel

Check container state and logs

cd ~/godoxy
docker compose ps
docker compose logs --tail=300

Investigate restart loops, malformed configuration, missing files, certificate-provider errors, bind failures, and container-runtime communication errors. Redact credentials, private hostnames, internal addresses, and tokens before sharing logs.

Confirm the listener

sudo ss -lntup

Confirm that the configured address and port are present. If another process owns the port, stop and resolve the conflict rather than changing ports in only one place.

Check hostname resolution

getent hosts godoxy.yourdomain.com

Replace the placeholder with your actual hostname. The result should point to the intended GoDoxy host from the machine performing the test. Split DNS can intentionally return an internal address on the LAN and a different answer elsewhere, so test from the same network perspective that will use the service.

Test the full local HTTPS request

curl -v https://godoxy.yourdomain.com/

If your verified listener uses a nonstandard port, append that actual port. This request checks name resolution, TCP reachability, TLS negotiation, certificate hostname validation, route selection, and the HTTP response. If the listener uses HTTP rather than HTTPS, test the exact verified HTTP URL instead and record where TLS is expected to terminate.

Test access control explicitly

A protected administrative interface should produce different outcomes for anonymous and authorized requests. From a browser profile without an existing session, verify that the WebUI is denied or redirected to the intended authentication flow. Then authenticate through the supported method and verify that only the intended account or network can gain access.

If anonymous users can reach route management, container controls, configuration, logs, or provider settings, do not proceed to public exposure. Stop and complete the access-control configuration using current GoDoxy documentation.

Back up, update, roll back, and restore GoDoxy safely

The current upstream extract provides installation instructions but does not provide a complete canonical Compose upgrade and rollback procedure. The following operational runbook therefore relies on the generated Compose model, recorded image references, and backups from your own deployment. Review it against the current repository and release notes before each change.

Define the backup scope

Back up the files required to reconstruct the deployment:

• compose.yml and any additional Compose files.
• .env, stored as sensitive configuration.
• The complete config directory, including route, middleware, and provider files.
• The certs directory if certificates and keys are locally managed there.
• The data directory and any other persistent path shown by docker compose config.
• The setup script or example files used for the installation.
• The resolved Compose output and exact container image identifier.

A file archive is useful only if it includes the real persistent paths. Inspect mounts first:

cd ~/godoxy
docker compose config > compose.resolved.yml
docker compose images

Store the resolved configuration carefully because environment expansion may expose sensitive values. Restrict access to both the archive and its metadata.

Create a point-in-time backup

For the simplest consistent file-level snapshot, schedule a maintenance window, stop the Compose project, copy the deployment directory to protected storage, and then restart it:

cd ~/godoxy
docker compose down
cd ..
tar -czf godoxy-backup-$(date +%Y%m%d-%H%M%S).tar.gz godoxy
cd godoxy
docker compose up -d
docker compose ps

This command assumes the relevant persistent files are below ~/godoxy. If the resolved Compose configuration mounts paths elsewhere, include those paths using a backup method appropriate for your system. Protect private keys and provider credentials in transit and at rest.

Prepare an update

1. Read the current GoDoxy release information and documentation for breaking changes.
2. Record the existing image reference and, where available, its immutable digest.
3. Back up all persistent paths.
4. Save copies of the current Compose, environment, and configuration files.
5. Review changes in the current setup script and example files instead of overwriting local files blindly.
6. Render the proposed Compose configuration with docker compose config.

If your reviewed Compose definition uses an image that should be pulled from its configured registry, the normal Compose sequence is:

cd ~/godoxy
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=300

Do not run pull as an automatic upgrade if you have not confirmed what image tag the Compose file uses. A mutable tag can retrieve a materially different build. Version pinning and change review are safer than assuming that every new image is backward compatible.

Validate after an update

Repeat the socket, DNS, TLS, WebUI route, authentication, and application-route checks. Verify that GoDoxy can still discover only the intended containers and that logs do not show certificate, provider, or runtime-control errors.

Plan rollback before changing anything

A rollback requires both the old configuration and an available old image. Restoring files while leaving a newer incompatible image in place may not restore service. Before the update, record the previous image reference or digest and confirm that it can be used again under your image-retention policy.

If validation fails, stop the new deployment, restore the backed-up files and persistent data, restore the recorded image reference in the Compose definition, and start the project again:

cd ~/godoxy
docker compose down
# Restore the reviewed backup and previous image reference here.
docker compose config
docker compose up -d
docker compose ps
docker compose logs --tail=300

The restore action is intentionally not represented by a universal command because backup destinations, ownership, encryption, and persistent paths differ. Use the restoration method you tested for your environment.

Perform a restore test

A backup is not verified until it has been restored outside the live directory. On an isolated test host or test environment, restore the files, inspect permissions, render the Compose configuration, and start the deployment only if doing so will not conflict with production DNS, certificates, ports, or container runtime access.

Confirm that the restored environment contains the expected routes and configuration, starts without errors, and answers a controlled test request. Never attach a restore test to a production Docker daemon if the restored GoDoxy instance could manage production containers.

Evaluate a Localtonet path without assuming direct compatibility

An HTTP-family tunnel is the relevant Localtonet category for a browser-based WebUI. Raw GoDoxy TCP or UDP routes require matching Localtonet TCP, UDP, or combined UDP/TCP tunnel types and are outside this WebUI-focused procedure.

The standard Localtonet lifecycle can be documented, but the final direct target must not be treated as verified until hostname and TLS behavior are established.

The compatibility matrix that must be completed

Localtonet HTTP and File Server tunnels can use Random Sub Domain, Custom Sub Domain, or Custom Domain process types. Exact availability can vary. Custom-domain DNS targets and validation requirements must come from the current dashboard and documentation. Do not copy DNS records from an older tutorial or another account.

Safe external verification criteria

If a future documented or tested configuration resolves the compatibility matrix, verify it from a separate internet connection. Confirm that:

• The browser reaches the intended WebUI rather than a default or unrelated route.
• The public certificate is valid for the public hostname.
• Any HTTPS upstream certificate is validated against the intended server name.
• Anonymous users cannot access administrative functions.
• The configured identity or network policy permits only intended administrators.
• GoDoxy logs show the expected hostname and route.
• Stopping the Localtonet tunnel removes the public path.

Protect GoDoxy, Docker control access, and the tunnel

GoDoxy can inspect and manage containers. That capability creates a sensitive trust boundary. The current generated Compose definition must be inspected to determine whether it mounts the Docker socket directly, uses GoDoxy's socket-proxy component, connects to Podman, or uses another control path. Do not describe any of those mechanisms as harmless.

Troubleshoot GoDoxy and Localtonet methodically

The container exits or repeatedly restarts

Run docker compose ps, inspect recent logs, and render the resolved configuration with docker compose config. Confirm that mounted files exist and have suitable permissions. Check for invalid configuration, missing environment values, certificate-provider failures, port conflicts, and inability to contact the configured container runtime.

No expected listener appears

Do not search for a guessed default port. Inspect .env, config, the resolved Compose output, and application logs. Then run ss -lntup. Because GoDoxy uses host network mode, another host process may already own the configured port.

The hostname does not resolve

Test the real hostname with getent hosts. Review A and AAAA records, wildcard placement, more-specific records, and DNS caching. A successful DNS answer still needs a reachable socket and matching GoDoxy route.

The WebUI works on the host but not from another LAN device

Check whether the listener is bound only to loopback. Review the Linux firewall and routing between devices. If the Localtonet client runs on the same host, loopback may be sufficient and safer than opening the listener to the whole LAN.

HTTPS reports a certificate error

Confirm that the requested hostname is covered by the certificate and reaches the intended route. Check the certificate chain, validity period, and DNS result. GoDoxy supports Let's Encrypt certificates with DNS-01 providers, but provider-specific credentials and configuration are not established by the evidence supplied here. Follow current GoDoxy documentation for the chosen provider.

The WebUI is reachable without authentication

Stop any public tunnel immediately. Verify that the selected authentication middleware or access policy is actually attached to the WebUI route, not merely defined elsewhere. Test with a private browser session and from a client outside any allowed network range.

The Localtonet tunnel was created but is unavailable

Confirm that the selected Localtonet device is connected and that the tunnel has been started. Verify that the client device can reach the configured local IP and port. Compare the tunnel's local protocol with the working local URL.

The Localtonet URL reaches the wrong GoDoxy route

Treat this as a hostname mismatch, not as evidence that GoDoxy is broken. Compare the browser-facing hostname, received Host header, configured GoDoxy route, and any upstream TLS name. Do not create an unrestricted default administrative route as a workaround.

The Localtonet connection fails against an HTTPS target

Determine which TLS server name is being sent to the upstream and which certificate GoDoxy presents. If current Localtonet documentation or the dashboard does not let you establish those facts, do not claim that the direct HTTPS-upstream topology is supported. Keep the service private while selecting a documented architecture.

GoDoxy does not discover an application container

Confirm that GoDoxy can contact the intended runtime and inspect the container. Review the container name, labels, and ports. The current project documentation uses proxy.aliases for subdomain aliases and otherwise falls back to container_name. Check the logs and WebUI after correcting metadata.

An update starts but local routes fail

Compare the new resolved Compose model and generated files with the recorded pre-update versions. Review release notes and logs. If the change cannot be corrected safely, restore the complete backup and previous image reference rather than mixing old configuration with an unverified new image.

Frequently asked questions