opensource/coder
3
0
Fork 0
mirror of https://github.com/coder/coder.git synced 2026-09-21 20:51:01 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs(docs/admin): document wildcard hostname suffixes (#27482)

Browse Source 
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.
This commit is contained in:
Thomas ILLIET
2026-07-24 15:10:19 +00:00
committed by GitHub
parent f96338110b
commit 0f1eafa17e
2 changed files with 34 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/admin/networking/wildcard-access-url.md
+30 -5
View File
@@ -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 <your-coder-server-ip>
```
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:
docs/admin/setup/index.md
+4 -4
View File
@@ -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