From 0f1eafa17eacc1e69524a72a71837addea31fa1c Mon Sep 17 00:00:00 2001 From: Thomas ILLIET Date: Fri, 24 Jul 2026 17:10:19 +0200 Subject: [PATCH] docs(docs/admin): document wildcard hostname suffixes (#27482) Documents wildcard hostname suffixes such as `*-apps.example.com`, which the existing application hostname parser and Helm chart already support. Explains the generated application hostname and the DNS and TLS wildcard required for each supported form. Also adds the suffix form to the installation summary. Validated with the repository's documentation linters and pre-commit hook, the hostname-pattern unit test, and an end-to-end workspace application on Coder v2.35.2. --- docs/admin/networking/wildcard-access-url.md | 35 +++++++++++++++++--- docs/admin/setup/index.md | 8 ++--- 2 files changed, 34 insertions(+), 9 deletions(-) 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