Configuring GoDoxy

Basic Config File

Here's a simple example of a configuration file:

providers:
  docker:
    local: $DOCKER_HOST

Understanding the Config File

The config.yml file is divided into several sections:

Environment Variables substitution

Environment variables can be substituted in every YAML string using the ${VAR_NAME} syntax.

autocert:
  ...
  options:
    auth_token: ${AUTH_TOKEN}

Auto SSL and Domain matching

Specify which domains your application should respond to.

autocert:
  provider: cloudflare
  email: your-email@example.com
  domains:
    - *.yourdomain.com
  # certificate_key_type: RSA2048  # optional; default EC256 (also EC384, RSA3072/4096/8192). Use RSA* if clients lack ECDSA (e.g. some IoT TLS)
match_domains:
  - yourdomain.com

See Certificates and domain matching

Entrypoint Configuration

This section defines how GoDoxy handles incoming requests.

entrypoint:
  proxy_protocol:
    # required accepts only these proxies; mixed also permits direct clients.
    mode: required
    trusted_proxies:
      - "172.18.0.10"
      - "10.0.0.0/8"

  middlewares:
    - use: CIDRWhitelist
      allow:
        - "127.0.0.1"
        - "10.0.0.0/8"
        - "192.168.0.0/16"
      status: 403
      message: "Forbidden"

  access_log:
    format: combined
    path: /app/logs/access.log
    filters: ...
    fields: ...

proxy_protocol.mode controls PROXY protocol handling for the web entrypoint and TCP route listeners:

• required accepts only listed proxies, and each connection must send a valid PROXY header.
• mixed requires a valid header from listed proxies but lets unlisted HTTP, TLS, and TCP clients connect directly without parsing their data as a header.
• disabled disables PROXY protocol parsing and ignores trusted_proxies.

Enabled modes require at least one trusted IP address or CIDR range.

support_proxy_protocol: true is deprecated. For compatibility it retains the old behavior—PROXY headers are optional and accepted from any peer—but GoDoxy warns at startup because clients can forge their apparent source address. Add a proxy_protocol block with mode required or mixed, add at least one trusted_proxies entry, and remove support_proxy_protocol.

Rules for unmatched hosts

entrypoint.rules.not_found handles an ordinary HTTP request only when its Host does not select a configured route and it is not handled as a short link. Route selection matches the request host against route aliases and domains; it does not match the URL path. A request for an unknown path on a known host still belongs to that route and does not run not_found. See Domain Matching for the host matching rules.

The HTTP entrypoint processes a request in this order:

1. Start access-log response recording when entrypoint.access_log is enabled.
2. Resolve the host route, including HTTPS SNI and inbound mTLS checks.
3. If a route matches, run its effective entrypoint middleware chain and then the route.
4. If no route matches, try the short-link handler. Short links run entrypoint middleware.
5. Otherwise, evaluate entrypoint.rules.not_found. If no rule completes the response, serve GoDoxy's normal 404 response or configured static 404 page.
6. Write the final response to the access log.

Route-resolution failures do not run not_found. For example, HTTPS SNI or mTLS route mismatches return 421 Misdirected Request, while other route-resolution failures return 500 Internal Server Error.

Entrypoint middleware does not automatically wrap the not_found handler. This keeps global redirect, authentication, rate-limit, and response middleware from replacing the unknown-host behavior. A not-found rule can explicitly run the request phase of a supported middleware with a middleware <name> { ... } action. This is opt-in, so unrelated entrypoint middleware remains excluded.

Not-found rules use the same block syntax, conditions, actions, phases, and default-rule behavior as Rule-Based Routing. See Conditions and Actions for the complete references.

Common terminating actions include proxy, route, redirect, error, serve, serve_file, handle, and require_basic_auth. Rules can also invoke request middleware, rewrite a request, change request or response fields, log, or send a notification. In this context, upstream, pass, and bypass continue to the normal 404 fallback because there is no matched route upstream.

Block-syntax example:

entrypoint:
  rules:
    not_found: |
      host legacy.example.com {
        redirect https://www.example.com
      }

      path /backend-health {
        error 404 "Not found"
      }

      default {
        middleware CloudflareRealIP {
        }
        log warn /dev/stderr "No route for $remote_addr $req_host$req_path"
      }

The non-terminating default rule applies CloudflareRealIP, writes the resolved client address to the log message, and then allows the normal 404 fallback. Because entrypoint access logging runs after the response, its combined log entry also uses the resolved client address. Replace the non-terminating actions with a terminating action such as proxy http://fallback-proxy:8080 when every otherwise-unmatched request should be handled elsewhere.

Setting Up Providers

providers:
  include:
    - file1.yml
    - file2.yml

  docker:
    local: ${DOCKER_HOST}
    remote-1: tcp://10.0.2.1:2375
    remote-2: ssh://root:1234@10.0.2.2

  agents:
    - 10.0.0.1:8899
    - 10.0.0.2:8899

  notification:
    - name: gotify
      provider: gotify
      url: https://gotify.example.com
      token: your-token

  proxmox:
    - url: https://pve.domain.com:8006/api2/json
      token_id: root@pam!abcdef
      secret: aaaa-bbbb-cccc-dddd
      no_tls_verify: true

  maxmind:
    account_id: 123456
    license_key: your-license-key
    database: geolite # or geoip2 if you have subscription

Docker Providers

A docker provider can be either:

• An URL string (e.g. tcp://10.0.2.1:2375)
• A structured object

Provider Configuration

TLS Configuration

providers:
  docker:
    local: ${DOCKER_HOST}
    remote_secured:
      scheme: https
      host: 10.0.2.1
      port: 2375
      tls:
        ca_file: /path/to/ca.pem
        cert_file: /path/to/cert.pem
        key_file: /path/to/key.pem

Default Values

defaults:
  healthcheck:
    interval: 5s
    timeout: 15s
    retries: 3

Homepage Settings

Configure how GoDoxy handles the app dashboard content shown inside the WebUI.

homepage:
  use_default_categories: true

See Dashboard Configurations

Built-in WebUI Route

GoDoxy serves the WebUI from embedded build assets (fileserver with SPA and embed://webui rules). A separate WebUI container is not required for normal use. The built-in WebUI is registered as a provider named webui after your configured providers are loaded.

webui field reference

These fields map to the root webui object in config.yml (see also WebUIConfig in the repository).

Aliases and environment fallback

If webui.aliases is omitted or empty after parsing, GoDoxy uses the legacy comma-separated env lookup (via goutils/env prefixes: GODOXY_, GOPROXY_, or unprefixed). The key is FRONTEND_ALIASES; default is godoxy.

Example:

webui:
  display_name: Home lab
  aliases:
    - godoxy.example.com
    - godoxy.local.app

Per-route hardening and logging

inbound_mtls_profile, middlewares, and access_log apply to every alias under webui (each hostname gets the same settings). For inbound mTLS, define inbound_mtls_profiles at the root of config.yml and reference a profile by name. See Inbound mTLS.

# Example: restrict who can open the WebUI and log access separately
webui:
  display_name: GoDoxy
  aliases:
    - godoxy
  middlewares:
    cidr_whitelist:
      status: 403
      message: IP not allowed
      allow:
        - 127.0.0.1
        - 10.0.0.0/8
        - 192.168.0.0/16
  access_log:
    format: combined
    path: /app/logs/webui-access.log

Conflicts and precedence

If an embedded WebUI alias collides with another route, GoDoxy logs a warning and the embedded WebUI route takes precedence for that alias.