Configuring Routes

Routes define how GoDoxy directs traffic to your applications. This guide covers all configuration methods, from Docker labels to route files

Quick Reference

Method	Use Case	Configuration Location
Docker Labels	Containerized apps	`docker-compose.yml` labels
Route Files	Non-Docker apps, VMs, LXC	`config/*.yml` files

Docker Container Configuration

Configure routes for containerized applications using Docker labels.

Basic Example

services:
  app:
    image: nginx
    container_name: my-app
    labels:
      # Hostname aliases (FQDN or subdomain)
      proxy.aliases: app, app.domain.com
      # Target port (auto-detected if not specified)
      proxy.#1.port: 80
      # Inactivity timeout before sleep (disabled by default)
      proxy.idle_timeout: 1h

Network Configuration

If your container uses multiple networks, specify which network GoDoxy should use:

services:
  app:
    image: app
    labels:
      proxy.network: app-network
    networks:
      - app-network
      - app-network-2

networks:
  app-network:
  app-network-2:

Health Check Configuration

Configure health checks to verify route availability:

labels:
  # Path to check (applied to all aliases)
  proxy.*.healthcheck.path: /ping
  # Check interval
  proxy.*.healthcheck.interval: 10s

Homepage Configuration

Customize how the route appears in the WebUI:

labels:
  proxy.#1.homepage: |
    name: App Name
    icon: "@selfhst/app.svg"
    description: Application description
    category: app
  # Hide specific alias from homepage
  proxy.#2.homepage.show: false

Route File Configuration

Route files configure routes for non-Docker applications (VMs, LXC containers, bare-metal).

File Structure

Place route files in the config/ directory with descriptive names:

config/
├── pve.yml        # Proxmox VE hosts
├── lxc.yml        # LXC containers
├── vps.yml        # Remote VPS instances
└── custom.yml     # Custom applications

Include Route Files

Add route files to providers.include in your config.yml:

providers:
  include:
    - config/pve.yml
    - config/lxc.yml
    - config/custom.yml

Basic Route File

# config/app.yml
app:
  host: 10.0.9.98
  port: 80
  homepage:
    name: Application
    icon: "@selfhst/app.svg"
    description: My application
    category: app

app-backend:
  host: 10.0.9.98
  port: 8080
  homepage:
    show: false

File Server Route

Serve static files from a directory:

blog:
  scheme: fileserver
  root: /app/blog/public
  spa: true
  index: index.html

Remote Agent Routes

Route traffic through a remote GoDoxy agent:

api.example.com:
  host: api.example.com
  scheme: https
  port: 443
  agent: https://10.0.1.2:8890

When an entrypoint middleware is active (e.g. OIDC), you can add per-route bypass rules that are promoted into the entrypoint middleware for that route only. This avoids the middleware being evaluated twice. See Entrypoint Overlay Promotion for details.

Configuration Reuse with YAML Anchors

Use YAML anchors to share configuration across routes:

x-proxy-common: &proxy-common
  scheme: https
  middlewares:
    hideXForwarded:
    modifyRequest:
      setHeaders:
        Host: $req_host

api.example.com:
  <<: *proxy-common
  host: api.example.com

admin.example.com:
  <<: *proxy-common
  host: admin.example.com

Label Syntax Reference

Full Namespace Syntax (Traefik-style)

services:
  app:
    labels:
      proxy.app.middlewares.request.set_headers.X-Custom-Header: value1,value2

Inline YAML Syntax

services:
  app:
    labels:
      proxy.app.middlewares.request.set_headers: |
        - X-Custom-Header: value1
        - X-Custom-Header2: value2

Index-Based Alias Configuration

Configure specific aliases by their position:

labels:
  proxy.aliases: app.domain.com, app-backend.domain.com
  # #1 points to first alias (app.domain.com)
  proxy.#1.port: 80
  # #2 points to second alias (app-backend.domain.com)
  proxy.#2.port: 8080

Property Reference

Core Proxy Properties

Property	Description	Default	Values
`scheme`	Route protocol	Auto-detected	`http`, `https`, `tcp`, `udp`, `fileserver`
`host`	Target hostname/IP	Docker: client IP File: `localhost`	IP or hostname
`port`	Listening and proxy port	`80:proxy_port`+`443:proxy_port` (proxy port auto-detected)	`1-65535` or `1-65535:1-65535`
`agent`	Upstream agent	None	Agent name or URL
`no_tls_verify`	Skip TLS verification	`false`	`true`, `false`

Stream Properties (TCP/UDP)

Property	Description	Default	Values
`port`	Listening and proxy port	`0:lowest_port` (random listening port)	`from:to` format
`bind`	Bind address	`0.0.0.0`	IP address
`relay_proxy_protocol_header`	Relay PROXY protocol header (TCP only)	`false`	boolean
`tls_termination`	Terminate TLS on shared `HTTPS_ADDR`, proxy plaintext upstream (TCP only; requires `autocert`)	`false`	boolean

TCP on the HTTPS listener (`HTTPS_ADDR`)

When a TCP route listens on the same address as the HTTPS entrypoint, GoDoxy uses TLS SNI to choose the route (short alias or FQDN, consistent with HTTP). By default the connection is TLS passthrough: ciphertext is copied to the upstream. Set tls_termination: true only on TCP routes listening on the configured shared HTTPS_ADDR; route validation rejects other listeners, and route registration rejects termination unless an autocert provider is configured. With termination enabled, GoDoxy matches ClientHello SNI, completes TLS with autocert, and forwards a plaintext stream to host and the proxy side of port.

HTTP-Specific Properties

Property	Description	Default	Values
`bind`	Bind to specific IP address	`0.0.0.0`	IP address
`no_tls_verify`	Skip TLS verification	`false`	boolean
`response_header_timeout`	Response header timeout	`60s`	duration
`max_conns_per_host`	Max upstream connections per host	`1000`	integer
`disable_compression`	Disable gzip compression	`false`	boolean
`ssl_server_name`	SNI server name	Auto	string
`ssl_trusted_certificate`	CA certificate path	None	file path
`ssl_certificate`	Client certificate path	None	file path
`ssl_certificate_key`	Client key path	None	file path
`ssl_protocols`	Allowed TLS versions	All supported	`TLSv1.0`–`TLSv1.3`

File Server Properties

Property	Description	Default	Values
`root`	Document root directory	Required	directory path
`spa`	Single-page application mode	`false`	boolean
`index`	Default index file for SPA mode	`/index.html`	filename

Sleep & Wake Properties

Property	Description	Default	Values
`idle_timeout`	Inactivity before sleep	Disabled	duration (e.g., `1h30s`)
`wake_timeout`	Wait time for wake	`30s`	duration
`stop_method`	Stop method after idle	`stop`	`stop`, `pause`, `kill`
`stop_timeout`	Timeout for stop command	`10s`	duration
`stop_signal`	Signal for stop/kill	Docker default	Signal name
`start_endpoint`	Required wake endpoint	Any	relative path
`no_loading_page`	Disable wake loading page	`false`	boolean

Label-Only Properties

Property	Description	Default	Values
`aliases`	Route hostnames	`container_name`	comma-separated
`exclude`	Exclude from proxy	`false`	boolean
`network`	Docker network	First available	network name

Docker Troubleshooting

Containers Not Appearing

Ensure containers expose their ports:

services:
  nginx:
    expose:
      - "80"

Common Issues

Port not detected: Verify expose or ports are defined
Wrong network: Specify proxy.network if using multiple networks
Alias not working: Ensure FQDN matches DNS records