diff --git a/docs/admin/networking/wildcard-access-url.md b/docs/admin/networking/wildcard-access-url.md index 9d558a7da0..57598cc591 100644 --- a/docs/admin/networking/wildcard-access-url.md +++ b/docs/admin/networking/wildcard-access-url.md @@ -22,19 +22,35 @@ The following tools require wildcard access URL: ## Configuration -`CODER_WILDCARD_ACCESS_URL` is necessary for [port forwarding](port-forwarding.md#dashboard) via the dashboard or running [coder_apps](../templates/index.md) on an absolute path. Set this to a wildcard subdomain that resolves to Coder (e.g. `*.coder.example.com`). +`CODER_WILDCARD_ACCESS_URL` is necessary for [port forwarding](port-forwarding.md#dashboard) via the dashboard or running [coder_apps](../templates/index.md) on an absolute path. +Set it to a wildcard hostname that resolves to Coder. +The value must contain exactly one `*` at the beginning of the hostname. +Coder replaces `*` with the generated application name, which stays within a single DNS label. -```sh -export CODER_WILDCARD_ACCESS_URL="*.coder.example.com" -coder server +Coder supports the wildcard as a full label or with a suffix in the first label: + +| Pattern | Example generated application hostname | Required DNS and TLS wildcard | +|----------------------|--------------------------------------------------|-------------------------------| +| `*.apps.example.com` | `8080--main--myworkspace--john.apps.example.com` | `*.apps.example.com` | +| `*-apps.example.com` | `8080--main--myworkspace--john-apps.example.com` | `*.example.com` | + +For example, use the suffix pattern to keep the Coder dashboard and application hostnames at the same DNS level: + +```dotenv +CODER_ACCESS_URL=https://apps.example.com +CODER_WILDCARD_ACCESS_URL=*-apps.example.com ``` +This configuration serves the dashboard from `https://apps.example.com` and a workspace application from a hostname such as `https://8080--main--myworkspace--john-apps.example.com`. + ### TLS Certificate Setup Wildcard access URLs require a TLS certificate that covers the wildcard domain. You have several options: > [!TIP] -> You can use a single certificate for both the access URL and wildcard access URL. The certificate CN or SANs must match the wildcard domain, such as `*.coder.example.com`. +> You can use a single certificate for both the access URL and wildcard access URL. +> For `*.apps.example.com`, the certificate must include `apps.example.com` and `*.apps.example.com`. +> For `*-apps.example.com` with an access URL of `apps.example.com`, a certificate for `*.example.com` covers both hostnames. #### Direct TLS Configuration @@ -82,6 +98,15 @@ Or alternatively, using a CNAME record: *.coder.example.com CNAME coder.example.com ``` +For a suffix pattern such as `*-apps.example.com`, DNS and TLS wildcards must cover the entire first label: + +```txt +*.example.com A +``` + +DNS providers and certificate authorities don't interpret `*-apps.example.com` as a wildcard record or certificate name. +Configure `*.example.com` instead, and ensure routing that wildcard to Coder doesn't conflict with other services under `example.com`. + ### Workspace Proxies If you're using [workspace proxies](workspace-proxies.md) for geo-distributed teams, each proxy requires its own wildcard access URL configuration: diff --git a/docs/admin/setup/index.md b/docs/admin/setup/index.md index fc3193e3f6..55419a1661 100644 --- a/docs/admin/setup/index.md +++ b/docs/admin/setup/index.md @@ -41,10 +41,10 @@ coder server > [!TIP] > Learn more about the [importance and benefits of wildcard access URLs](../networking/wildcard-access-url.md) -`CODER_WILDCARD_ACCESS_URL` is necessary for -[port forwarding](../networking/port-forwarding.md#dashboard) via the dashboard -or running [coder_apps](../templates/index.md) on an absolute path. Set this to -a wildcard subdomain that resolves to Coder (e.g. `*.coder.example.com`). +`CODER_WILDCARD_ACCESS_URL` is necessary for [port forwarding](../networking/port-forwarding.md#dashboard) via the dashboard or running [coder_apps](../templates/index.md) on an absolute path. +Set it to a wildcard hostname that resolves to Coder, such as `*.coder.example.com` or `*-coder.example.com`. +The suffix form creates application hostnames such as `8080--main--myworkspace--john-coder.example.com`. +It requires a DNS record and TLS certificate for `*.example.com`. > [!NOTE] > We do not recommend using a top-level-domain for Coder wildcard access