From bc3b0f3beacc0ed2e8db47893c4e8c0ed366999e Mon Sep 17 00:00:00 2001 From: Kacper Sawicki Date: Fri, 5 Sep 2025 12:52:32 +0000 Subject: [PATCH 1/8] feat(docs): add wildcard access url documentation page --- docs/admin/networking/wildcard-access-url.md | 73 ++++++++++++++++++++ docs/admin/setup/index.md | 3 + docs/manifest.json | 5 ++ 3 files changed, 81 insertions(+) create mode 100644 docs/admin/networking/wildcard-access-url.md diff --git a/docs/admin/networking/wildcard-access-url.md b/docs/admin/networking/wildcard-access-url.md new file mode 100644 index 0000000000000..8981c627a9a70 --- /dev/null +++ b/docs/admin/networking/wildcard-access-url.md @@ -0,0 +1,73 @@ +# Wildcard Access URLs + +> [!IMPORTANT] +> **Wildcard access URL is essential for many development workflows in Coder.** Web IDEs (code-server, VS Code Web, JupyterLab) and some development frameworks work significantly better with subdomain-based access rather than path-based URLs. + +Wildcard access URLs unlock Coder's full potential for modern development workflows. While optional for basic SSH usage, this feature becomes essential when teams need web applications, development previews, or browser-based tools. + +## Why configure wildcard access URLs? + +### Key benefits + +- **Eliminates port conflicts**: Each application gets a unique subdomain (e.g., `8080--main--myworkspace--john.coder.example.com`) +- **Enhanced security**: Applications run in isolated subdomains with separate browser security contexts +- **Better compatibility**: Web-based IDEs, mobile devices, and third-party integrations work reliably with standard HTTPS URLs + +### When wildcard access URL is required + +Wildcard access URL enables subdomain-based workspace applications, which is required for: + +- **Web IDEs**: code-server, VS Code Web, JupyterLab, RStudio work better with dedicated subdomains +- **Modern development frameworks**: Vite, React dev server, Next.js, and similar tools expect to control the entire domain for features like hot module replacement and asset serving +- **Development servers with preview URLs**: Applications that generate preview URLs or use absolute paths +- **Applications that don't support path-based routing**: Some tools like KasmVNC cannot function with path-based access +- **Secure development environment isolation**: Each development application runs on its own subdomain + +## 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`). + +```bash +export CODER_WILDCARD_ACCESS_URL="*.coder.example.com" +coder server +``` + +### DNS Setup + +You'll need to configure DNS to point wildcard subdomains to your Coder server: + +```text +*.coder.example.com A +``` + +## Template Configuration + +In your Coder templates, enable subdomain applications using the `subdomain` parameter: + +```hcl +resource "coder_app" "code-server" { + agent_id = coder_agent.main.id + slug = "code-server" + display_name = "VS Code" + url = "http://localhost:8080" + icon = "/icon/code.svg" + subdomain = true + share = "owner" +} +``` + +## Troubleshooting + +### Applications not accessible + +If workspace applications are not working: + +1. Verify the `CODER_WILDCARD_ACCESS_URL` environment variable is configured correctly +2. Check DNS resolution for wildcard subdomains +3. Ensure TLS certificates cover the wildcard domain +4. Confirm template `coder_app` resources have `subdomain = true` + +## See also + +- [Port Forwarding](port-forwarding.md) - Access workspace applications via dashboard when wildcard URL is not configured +- [Workspace Proxies](workspace-proxies.md) - Improve performance for geo-distributed teams using wildcard URLs diff --git a/docs/admin/setup/index.md b/docs/admin/setup/index.md index a0ffaa0f5211a..ea36467cfa106 100644 --- a/docs/admin/setup/index.md +++ b/docs/admin/setup/index.md @@ -38,6 +38,9 @@ coder server ## Wildcard access URL +> [!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 diff --git a/docs/manifest.json b/docs/manifest.json index 9359fb6f1da33..759c72dfe6c9f 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -770,6 +770,11 @@ "path": "./admin/networking/high-availability.md", "state": ["premium"] }, + { + "title": "Wildcard Access URL", + "description": "Learn about wildcard access URL in Coder deployments", + "path": "./admin/networking/wildcard-access-url.md" + }, { "title": "Troubleshooting", "description": "Troubleshoot networking issues in Coder", From 620378623fc6a2f3b12d9891c3dbf2dd743f328b Mon Sep 17 00:00:00 2001 From: Kacper Sawicki Date: Mon, 8 Sep 2025 14:16:59 +0000 Subject: [PATCH 2/8] Apply review suggestions --- docs/admin/networking/wildcard-access-url.md | 101 +++++++++++++++---- 1 file changed, 84 insertions(+), 17 deletions(-) diff --git a/docs/admin/networking/wildcard-access-url.md b/docs/admin/networking/wildcard-access-url.md index 8981c627a9a70..b3fe083493d8a 100644 --- a/docs/admin/networking/wildcard-access-url.md +++ b/docs/admin/networking/wildcard-access-url.md @@ -1,27 +1,25 @@ # Wildcard Access URLs -> [!IMPORTANT] -> **Wildcard access URL is essential for many development workflows in Coder.** Web IDEs (code-server, VS Code Web, JupyterLab) and some development frameworks work significantly better with subdomain-based access rather than path-based URLs. - -Wildcard access URLs unlock Coder's full potential for modern development workflows. While optional for basic SSH usage, this feature becomes essential when teams need web applications, development previews, or browser-based tools. +Wildcard access URLs unlock Coder's full potential for modern development workflows. While optional for basic SSH usage, this feature becomes essential when teams need web applications, development previews, or browser-based tools. **Wildcard access URL is essential for many development workflows in Coder** - Web IDEs (code-server, VS Code Web, JupyterLab) and some development frameworks work significantly better with subdomain-based access rather than path-based URLs. ## Why configure wildcard access URLs? ### Key benefits -- **Eliminates port conflicts**: Each application gets a unique subdomain (e.g., `8080--main--myworkspace--john.coder.example.com`) -- **Enhanced security**: Applications run in isolated subdomains with separate browser security contexts -- **Better compatibility**: Web-based IDEs, mobile devices, and third-party integrations work reliably with standard HTTPS URLs +- **Enables port access**: Each application gets a unique subdomain with port support (e.g., `8080--main--myworkspace--john.coder.example.com`) +- **Enhanced security**: Applications run in isolated subdomains with separate browser security contexts and prevents access to the Coder API from malicious JavaScript +- **Better compatibility**: Most applications are designed to work at the root of a hostname rather than at a subpath, making subdomain access more reliable -### When wildcard access URL is required +### Applications that require subdomain access -Wildcard access URL enables subdomain-based workspace applications, which is required for: +The following applications have issues or don't work without wildcard access URLs: -- **Web IDEs**: code-server, VS Code Web, JupyterLab, RStudio work better with dedicated subdomains -- **Modern development frameworks**: Vite, React dev server, Next.js, and similar tools expect to control the entire domain for features like hot module replacement and asset serving -- **Development servers with preview URLs**: Applications that generate preview URLs or use absolute paths -- **Applications that don't support path-based routing**: Some tools like KasmVNC cannot function with path-based access -- **Secure development environment isolation**: Each development application runs on its own subdomain +- **KasmVNC**: Cannot function with path-based access +- **Vite dev server**: Hot module replacement and asset serving issues with path-based routing +- **React dev server**: Similar issues with hot reloading and absolute path references +- **Next.js development server**: Asset serving and routing conflicts with path-based access +- **JupyterLab**: More complex template configuration and security risks when using path-based routing +- **RStudio**: More complex template configuration and security risks when using path-based routing ## Configuration @@ -32,14 +30,75 @@ export CODER_WILDCARD_ACCESS_URL="*.coder.example.com" coder server ``` +### 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 must match the wildcard domain, such as `*.coder.example.com`. + +#### Direct TLS Configuration + +Configure Coder to handle TLS directly using the wildcard certificate: + +```bash +export CODER_TLS_ENABLE=true +export CODER_TLS_CERT_FILE=/path/to/wildcard.crt +export CODER_TLS_KEY_FILE=/path/to/wildcard.key +``` + +See [TLS & Reverse Proxy](../setup/index.md#tls--reverse-proxy) for detailed configuration options. + +#### Reverse Proxy with Let's Encrypt + +Use a reverse proxy to handle TLS termination with automatic certificate management: + +- [NGINX with Let's Encrypt](../../tutorials/reverse-proxy-nginx.md) +- [Apache with Let's Encrypt](../../tutorials/reverse-proxy-apache.md) +- [Caddy reverse proxy](../../tutorials/reverse-proxy-caddy.md) + ### DNS Setup You'll need to configure DNS to point wildcard subdomains to your Coder server: +> [!NOTE] +> We do not recommend using a top-level-domain for Coder wildcard access +> (for example `*.workspaces`), even on private networks with split-DNS. Some +> browsers consider these "public" domains and will refuse Coder's cookies, +> which are vital to the proper operation of this feature. + ```text *.coder.example.com A ``` +Or alternatively, using a CNAME record: + +```text +*.coder.example.com CNAME coder.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: + +```bash +# Main Coder server +export CODER_WILDCARD_ACCESS_URL="*.coder.example.com" + +# Sydney workspace proxy +export CODER_WILDCARD_ACCESS_URL="*.sydney.coder.example.com" + +# London workspace proxy +export CODER_WILDCARD_ACCESS_URL="*.london.coder.example.com" +``` + +Each proxy's wildcard domain must have corresponding DNS records: + +```text +*.sydney.coder.example.com A +*.london.coder.example.com A +``` + ## Template Configuration In your Coder templates, enable subdomain applications using the `subdomain` parameter: @@ -62,12 +121,20 @@ resource "coder_app" "code-server" { If workspace applications are not working: -1. Verify the `CODER_WILDCARD_ACCESS_URL` environment variable is configured correctly -2. Check DNS resolution for wildcard subdomains +1. Verify the `CODER_WILDCARD_ACCESS_URL` environment variable is configured correctly: + - Check the deployment settings in the Coder dashboard (Settings > Deployment) + - Ensure it matches your wildcard domain (e.g., `*.coder.example.com`) + - Restart the Coder server if you made changes to the environment variable +2. Check DNS resolution for wildcard subdomains: + + ```bash + dig test.coder.example.com + nslookup test.coder.example.com + ``` + 3. Ensure TLS certificates cover the wildcard domain 4. Confirm template `coder_app` resources have `subdomain = true` ## See also -- [Port Forwarding](port-forwarding.md) - Access workspace applications via dashboard when wildcard URL is not configured - [Workspace Proxies](workspace-proxies.md) - Improve performance for geo-distributed teams using wildcard URLs From 56699f34509f249ed55645fd12d609fcf413c759 Mon Sep 17 00:00:00 2001 From: Kacper Sawicki Date: Tue, 9 Sep 2025 13:14:22 +0200 Subject: [PATCH 3/8] Apply suggestions from code review Co-authored-by: Dean Sheather --- docs/admin/networking/wildcard-access-url.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/admin/networking/wildcard-access-url.md b/docs/admin/networking/wildcard-access-url.md index b3fe083493d8a..1f74f617b3dfc 100644 --- a/docs/admin/networking/wildcard-access-url.md +++ b/docs/admin/networking/wildcard-access-url.md @@ -1,12 +1,12 @@ # Wildcard Access URLs -Wildcard access URLs unlock Coder's full potential for modern development workflows. While optional for basic SSH usage, this feature becomes essential when teams need web applications, development previews, or browser-based tools. **Wildcard access URL is essential for many development workflows in Coder** - Web IDEs (code-server, VS Code Web, JupyterLab) and some development frameworks work significantly better with subdomain-based access rather than path-based URLs. +Wildcard access URLs unlock Coder's full potential for modern development workflows. While optional for basic SSH usage, this feature becomes essential when teams need web applications, development previews, or browser-based tools. **Wildcard access URLs are essential for many development workflows in Coder** - Web IDEs (code-server, VS Code Web, JupyterLab) and some development frameworks work significantly better with subdomain-based access rather than path-based URLs. ## Why configure wildcard access URLs? ### Key benefits -- **Enables port access**: Each application gets a unique subdomain with port support (e.g., `8080--main--myworkspace--john.coder.example.com`) +- **Enables port access**: Each application gets a unique subdomain with port support (e.g. `8080--main--myworkspace--john.coder.example.com`) - **Enhanced security**: Applications run in isolated subdomains with separate browser security contexts and prevents access to the Coder API from malicious JavaScript - **Better compatibility**: Most applications are designed to work at the root of a hostname rather than at a subpath, making subdomain access more reliable @@ -35,7 +35,7 @@ coder server 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 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. The certificate CN or SANs must match the wildcard domain, such as `*.coder.example.com`. #### Direct TLS Configuration From dee94f959975908d65d36eee81ea2bc60188d2f6 Mon Sep 17 00:00:00 2001 From: Kacper Sawicki Date: Thu, 11 Sep 2025 12:48:54 +0200 Subject: [PATCH 4/8] Update docs/admin/networking/wildcard-access-url.md Co-authored-by: Atif Ali --- docs/admin/networking/wildcard-access-url.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/admin/networking/wildcard-access-url.md b/docs/admin/networking/wildcard-access-url.md index 1f74f617b3dfc..bfed9c2e5186c 100644 --- a/docs/admin/networking/wildcard-access-url.md +++ b/docs/admin/networking/wildcard-access-url.md @@ -6,7 +6,7 @@ Wildcard access URLs unlock Coder's full potential for modern development workfl ### Key benefits -- **Enables port access**: Each application gets a unique subdomain with port support (e.g. `8080--main--myworkspace--john.coder.example.com`) +- **Enables port access**: Each application gets a unique subdomain with [port support](https://coder.com/docs/user-guides/workspace-access/port-forwarding#dashboard) (e.g. `8080--main--myworkspace--john.coder.example.com`). - **Enhanced security**: Applications run in isolated subdomains with separate browser security contexts and prevents access to the Coder API from malicious JavaScript - **Better compatibility**: Most applications are designed to work at the root of a hostname rather than at a subpath, making subdomain access more reliable From a4ee404b9adecf5f52f60ae9e77da396452e16ed Mon Sep 17 00:00:00 2001 From: Kacper Sawicki Date: Thu, 11 Sep 2025 11:10:12 +0000 Subject: [PATCH 5/8] Apply review suggestions --- docs/admin/networking/wildcard-access-url.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/admin/networking/wildcard-access-url.md b/docs/admin/networking/wildcard-access-url.md index bfed9c2e5186c..310aec2567990 100644 --- a/docs/admin/networking/wildcard-access-url.md +++ b/docs/admin/networking/wildcard-access-url.md @@ -14,7 +14,6 @@ Wildcard access URLs unlock Coder's full potential for modern development workfl The following applications have issues or don't work without wildcard access URLs: -- **KasmVNC**: Cannot function with path-based access - **Vite dev server**: Hot module replacement and asset serving issues with path-based routing - **React dev server**: Similar issues with hot reloading and absolute path references - **Next.js development server**: Asset serving and routing conflicts with path-based access @@ -25,6 +24,10 @@ The following applications have issues or don't work without wildcard access URL `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`). +> [!TIP] +> For complete setup instructions, see [Wildcard Access URL Configuration](../setup/index.md#wildcard-access-url) in the main setup guide. + + ```bash export CODER_WILDCARD_ACCESS_URL="*.coder.example.com" coder server From 2ff6d2b3d338fcd049f459561c003d59a70de25a Mon Sep 17 00:00:00 2001 From: Kacper Sawicki Date: Thu, 11 Sep 2025 11:42:11 +0000 Subject: [PATCH 6/8] Fix lint --- docs/admin/networking/wildcard-access-url.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/admin/networking/wildcard-access-url.md b/docs/admin/networking/wildcard-access-url.md index 310aec2567990..1fd7a3d94396c 100644 --- a/docs/admin/networking/wildcard-access-url.md +++ b/docs/admin/networking/wildcard-access-url.md @@ -27,7 +27,6 @@ The following applications have issues or don't work without wildcard access URL > [!TIP] > For complete setup instructions, see [Wildcard Access URL Configuration](../setup/index.md#wildcard-access-url) in the main setup guide. - ```bash export CODER_WILDCARD_ACCESS_URL="*.coder.example.com" coder server From 8ea6f793bec9aa3ce9a3afbc8a43198d0a4b99a0 Mon Sep 17 00:00:00 2001 From: Kacper Sawicki Date: Fri, 12 Sep 2025 18:27:12 +0200 Subject: [PATCH 7/8] Update docs/admin/networking/wildcard-access-url.md Co-authored-by: david-fraley <67079030+david-fraley@users.noreply.github.com> --- docs/admin/networking/wildcard-access-url.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/admin/networking/wildcard-access-url.md b/docs/admin/networking/wildcard-access-url.md index 1fd7a3d94396c..c990e007a42da 100644 --- a/docs/admin/networking/wildcard-access-url.md +++ b/docs/admin/networking/wildcard-access-url.md @@ -12,7 +12,7 @@ Wildcard access URLs unlock Coder's full potential for modern development workfl ### Applications that require subdomain access -The following applications have issues or don't work without wildcard access URLs: +The following tools require wildcard access URLs: - **Vite dev server**: Hot module replacement and asset serving issues with path-based routing - **React dev server**: Similar issues with hot reloading and absolute path references From b13e8043010d69f0a70bc4ffa5622ddbd1dd8451 Mon Sep 17 00:00:00 2001 From: Kacper Sawicki Date: Fri, 12 Sep 2025 16:30:40 +0000 Subject: [PATCH 8/8] Apply review suggestions --- docs/admin/networking/wildcard-access-url.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/docs/admin/networking/wildcard-access-url.md b/docs/admin/networking/wildcard-access-url.md index c990e007a42da..44afba2e5bb2d 100644 --- a/docs/admin/networking/wildcard-access-url.md +++ b/docs/admin/networking/wildcard-access-url.md @@ -12,7 +12,7 @@ Wildcard access URLs unlock Coder's full potential for modern development workfl ### Applications that require subdomain access -The following tools require wildcard access URLs: +The following tools require wildcard access URL: - **Vite dev server**: Hot module replacement and asset serving issues with path-based routing - **React dev server**: Similar issues with hot reloading and absolute path references @@ -24,9 +24,6 @@ The following tools require wildcard access URLs: `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`). -> [!TIP] -> For complete setup instructions, see [Wildcard Access URL Configuration](../setup/index.md#wildcard-access-url) in the main setup guide. - ```bash export CODER_WILDCARD_ACCESS_URL="*.coder.example.com" coder server