Basics

Docker Image

Tag	Description
`latest`	Stable release
`nightly`	Experimental release
`vx.y.z`	Stable release

Proxy ghcr.io/yusing/godoxy:<tag>
Agent ghcr.io/yusing/godoxy-agent:<tag>

Starting from v0.29.0, the WebUI is served by the godoxy image from embedded static assets; no separate frontend image or container is required.

Secure your containers

GoDoxy will work without mapping ports to the host.

Remove ports section in your docker-compose.yml file.

Doing this will make your host has only one exposed service, which is GoDoxy.

Environment variables

Core

Also works with old prefix GOPROXY_ or without prefix like API_USER.

Environment Variable	Description	Default	Values
`GODOXY_HTTP_ADDR`	HTTP server listening address	`:80`	`[host]:port`
`GODOXY_HTTPS_ADDR`	HTTPS server listening address (if enabled)	`:443`	`[host]:port`
`GODOXY_API_ADDR`	API server listening address	`127.0.0.1:8888`	`[host]:port`
`GODOXY_LOCAL_API_ADDR`	Local API server listening address for unauthenticated access	-	`[host]:port`
`GODOXY_HTTP3_ENABLED`	Enable HTTP/3	`true`	boolean
`GODOXY_DEBUG`	Enable debug behaviors and logging	`false`	boolean

Authentication

Common

Environment Variable	Description	Default	Values
`GODOXY_API_JWT_SECURE`	Secure flag for JWT cookie	`true`	boolean
`GODOXY_API_JWT_SECRET`	Base64 JWT secret for api server	random (you will have to login again after restarting GoDoxy)	string
`GODOXY_API_JWT_TOKEN_TTL`	JWT Time-to-live	`24h`	duration
`GODOXY_FRONTEND_ALIASES`	Legacy embedded WebUI route aliases; prefer `webui.aliases` in `config.yml`	`godoxy`	comma-separated hostnames

To use WebUI without HTTPS, set GODOXY_API_JWT_SECURE to false.

Not recommended.

User Password Auth

Environment Variable	Description	Default	Values
`GODOXY_API_USER`	WebUI login username	none	string
`GODOXY_API_PASSWORD`	WebUI login password	none	string

Both values must be set when using username/password authentication. GoDoxy rejects startup when either value is missing unless OIDC is enabled or authentication is explicitly disabled.

OpenID Connect (OIDC)

OIDC provides enterprise authentication via external identity providers.

See OIDC Configuration for setup instructions.

Metrics

Environment Variable	Description	Default	Values
`GODOXY_METRICS_DISABLE_CPU`	Disable cpu usage collection	`false`	boolean
`GODOXY_METRICS_DISABLE_MEMORY`	Disable memory usage collection	`false`	boolean
`GODOXY_METRICS_DISABLE_DISK`	Disable disk usage, I/O collection	`false`	boolean
`GODOXY_METRICS_DISABLE_NETWORK`	Disable network I/O collection	`false`	boolean
`GODOXY_METRICS_DISABLE_SENSORS`	Disable sensors info collection	`false`	boolean

Behaviors

Default URL: <container_name>.yourdomain.com

Container Proxying

ALL CONTAINERS are proxied by default, unless any of the following is true:

The label proxy.exclude includes proxy (true, proxy, or all)
The container is from a provider in explicit only mode (name with a trailing exclamation mark !)
The container is a backend service (e.g.: headless browsers, databases, etc.)
The container doesn't have any exposed port
The container name starts with buildx_
The alias starts with x- or ends with -old

Explicitly Enable Container Proxying

GoDoxy < v0.9 - set label proxy.aliases
GoDoxy >= v0.9 - set any label starting with proxy.

Health Monitoring

Health monitoring is enabled by default for ALL CONTAINERS, including the excluded ones.

Docker healthchecks are preferred when available. GoDoxy's fallback probe can be disabled by setting healthcheck.disable: true per route in the route file or in the docker labels. Docker health monitoring remains enabled.

For every route of a Docker container, set proxy.exclude: healthcheck. Use proxy.exclude: proxy,healthcheck or proxy.exclude: all to also exclude the container from proxying. The boolean value true keeps its original behavior and excludes only proxying.

services:
  app:
    labels:
      proxy.exclude: all

Use JSON Schema in IDEs

If you are unsure about what it is, ignore this

Using JSON schema allows static checking in IDEs. For VSCode, copy .vscode/settings.example.json to .vscode/settings.json (under root directory of GoDoxy) and modify it to fit your needs