Configuring GoDoxy
Basic Config File
Here's a simple example of a configuration file:
providers:
docker:
local: $DOCKER_HOSTUnderstanding the Config File
The config.yml file is divided into several sections:
| Section | Description |
|---|---|
acl | Handles access control |
autocert | Handles SSL certificate settings |
entrypoint | Manages GoDoxy entrypoints (port 80 and 443) |
↳ middlewares | Defines middleware settings |
↳ access_log | Configures access logs |
providers | Sets up orchestrators (required) |
↳ include | Includes route configuration files |
↳ docker | Configures Docker providers |
↳ agents | GoDoxy agents |
↳ proxmox | Proxmox credentials |
↳ notification | Configures notifications for health monitoring |
↳ maxmind | MaxMind credentials |
match_domains | List of domains to match |
defaults | Default values |
homepage | Configures homepage settings |
webui | Embedded WebUI: aliases, optional inbound_mtls_profile, middlewares, access_log |
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.comSee Certificates and domain matching
Entrypoint Configuration
This section defines how GoDoxy handles incoming requests.
entrypoint:
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: ...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 subscriptionDocker Providers
A docker provider can be either:
- An URL string (e.g.
tcp://10.0.2.1:2375) - A structured object
Provider Configuration
Prop
Type
TLS Configuration
Prop
Type
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.pemDefault Values
defaults:
healthcheck:
interval: 5s
timeout: 15s
retries: 3Homepage Settings
Configure how GoDoxy handles the app dashboard content shown inside the WebUI.
homepage:
use_default_categories: trueBuilt-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).
Prop
Type
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.
| Variable (any matching prefix) | Role |
|---|---|
…FRONTEND_ALIASES | Comma-separated hostnames for the embedded WebUI when webui.aliases is not set |
Example:
webui:
aliases:
- godoxy.example.com
- godoxy.local.appPer-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:
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.logConflicts 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.