Domain Matching

An alias can be:

• a short alias like app
• an FQDN (Fully Qualified Domain Name) alias like app.example.com
• a leading-label wildcard alias like *.example.com

DockerCopy Anchor Link

By default, the container name is used as the short alias unless proxy.aliases is set.

GeneralCopy Anchor Link

Without match_domainsCopy Anchor Link

If match_domains is not set in config.yml, below will match route with short alias app:

• app.anydomain.com
• app.*.anydomain.com
• ...

Below will match route with FQDN alias app.example.com:

• app.example.com

Below will match route with wildcard alias *.example.com:

• foo.example.com
• bar.example.com

And will not match:

• example.com
• foo.bar.example.com

Using match_domainsCopy Anchor Link

Use this to restrict which base domains are valid.

With match_domains in config.yml:

match_domains:
  - example.com
  - example.org

Then a short alias app can be accessed only at:

• app.example.com
• app.example.org

And a route with FQDN alias app.example.com can be accessed at:

• app.example.com

And a wildcard alias *.example.com can be accessed only at one-label subdomains such as:

• foo.example.com
• bar.example.com

but not:

• foo.bar.example.com

Public URLs and dashboard linksCopy Anchor Link

The route list and detail APIs expose public_urls for HTTP routes. These URLs come from configured domains and listeners, so calling the API by IP address or through another hostname does not change them.

With match_domains: [example.com, example.org], app.dev produces https://app.dev.example.com and https://app.dev.example.org. An alias equal to a configured domain, or ending in that domain at a label boundary, is used as-is. For example, app.example.com is complete, while notexample.com still receives the configured domain suffix.

HTTPS is used when the shared HTTPS listener is enabled; otherwise HTTP is used. Nondefault listener ports are included. Routes on dedicated HTTPS ports use those ports. External port or protocol translation is not inferred. Excluded routes and TCP/UDP streams do not have public HTTP URLs.

The dashboard uses the first URL in configuration order unless homepage.url overrides it. With no match domains, dotted aliases are used as-is. Undotted aliases have no API public_urls, but dashboard links still use the requesting browser's hostname and protocol.

PriorityCopy Anchor Link

Host resolution order is:

1. existing exact/FQDN or short-alias domain match
2. wildcard alias fallback

This keeps normal exact-route matching fast while still allowing wildcard aliases.

Route file exampleCopy Anchor Link

Quote wildcard aliases in YAML route files:

"*.example.com":
  host: 10.0.0.20
  port: 8080

Use case example for match_domainsCopy Anchor Link

Given your main domain is my.app:

• Add my.app to autocert.domains and match_domains in config.yml.

  Copy Text

  autocert:
    domains:
      - my.app
  match_domains:
    - my.app

• Use short aliases like adguard and sonarr when you want them accessible under your main domain.

  Copy Text

  services:
    adguard: # adguard.my.app
      ...
      labels:
        proxy.aliases: adguard
    sonarr: # sonarr.my.app
      ...
      labels:
        proxy.aliases: sonarr

• Use FQDN aliases like adguard.other.app and sonarr.other.app when you want them accessible under other domains.

  Copy Text

  # docker compose
  services:
    adguard:
      ...
      labels:
        proxy.aliases: adguard.other.app
    sonarr:
      ...
      labels:
        proxy.aliases: sonarr.other.app
  
  # config.yml
  autocert:
    domains:
      - my.app