Basics

Docker ImageCopy Anchor Link

• 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.

Current versionCopy Anchor Link

Secure your containersCopy Anchor Link

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

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

Environment variablesCopy Anchor Link

See Environment Variables for the complete generated setting table, defaults, prefix migration, and startup diagnostics. Copy .env.example to .env, configure credentials, and uncomment only overrides. Compose uses socket-proxy and passes the configured Docker endpoint unchanged.

Configuration interpolation and provider recoveryCopy Anchor Link

Use braces for environment references in YAML, for example:

providers:
  docker:
    local: unix://${DOCKER_SOCKET}

References work both as whole values and inside strings. Quoting the YAML value is optional; env contents remain literal data. Missing variables are errors. The exact Docker provider value $DOCKER_HOST is a special shorthand that uses the same prefixed lookup order and defaults to unix:///var/run/docker.sock. Other bare $VAR references in Docker endpoints are rejected with a configuration error. The selected DOCKER_HOST endpoint is treated as local for public/private container address discovery.

Unavailable Docker and agent providers retry startup automatically, with backoff from 3 to 30 seconds. They are reported as degraded while retrying. A successful retry reloads routes without requiring a container event or config save. Initial activation reports remain snapshots; consult recovery logs and the current route inventory for later results. A config reload or shutdown cancels the old retries.

AuthenticationCopy Anchor Link

User Password AuthCopy Anchor Link

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)Copy Anchor Link

OIDC provides enterprise authentication via external identity providers.

See OIDC Configuration for setup instructions.

BehaviorsCopy Anchor Link

Default URL: <container_name>.yourdomain.com

Container ProxyingCopy Anchor Link

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 ProxyingCopy Anchor Link

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

Health MonitoringCopy Anchor Link

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 IDEsCopy Anchor Link

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