Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit f9f0ebb

Browse files
kacpersawdeansheathermatifalidavid-fraley
authored
feat(docs): add wildcard access url documentation page (coder#19713)
Closes coder#19607 This pull request adds a new guide about wildcard access URLs. --------- Co-authored-by: Dean Sheather <[email protected]> Co-authored-by: Atif Ali <[email protected]> Co-authored-by: david-fraley <[email protected]>
1 parent 854f3c0 commit f9f0ebb

File tree

3 files changed

+147
-0
lines changed

3 files changed

+147
-0
lines changed

‎docs/admin/networking/wildcard-access-url.md

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
# Wildcard Access URLs
2+
3+
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.
4+
5+
## Why configure wildcard access URLs?
6+
7+
### Key benefits
8+
9+
- **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`).
10+
- **Enhanced security**: Applications run in isolated subdomains with separate browser security contexts and prevents access to the Coder API from malicious JavaScript
11+
- **Better compatibility**: Most applications are designed to work at the root of a hostname rather than at a subpath, making subdomain access more reliable
12+
13+
### Applications that require subdomain access
14+
15+
The following tools require wildcard access URL:
16+
17+
- **Vite dev server**: Hot module replacement and asset serving issues with path-based routing
18+
- **React dev server**: Similar issues with hot reloading and absolute path references
19+
- **Next.js development server**: Asset serving and routing conflicts with path-based access
20+
- **JupyterLab**: More complex template configuration and security risks when using path-based routing
21+
- **RStudio**: More complex template configuration and security risks when using path-based routing
22+
23+
## Configuration
24+
25+
`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`).
26+
27+
```bash
28+
export CODER_WILDCARD_ACCESS_URL="*.coder.example.com"
29+
coder server
30+
```
31+
32+
### TLS Certificate Setup
33+
34+
Wildcard access URLs require a TLS certificate that covers the wildcard domain. You have several options:
35+
36+
> [!TIP]
37+
> 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`.
38+
39+
#### Direct TLS Configuration
40+
41+
Configure Coder to handle TLS directly using the wildcard certificate:
42+
43+
```bash
44+
export CODER_TLS_ENABLE=true
45+
export CODER_TLS_CERT_FILE=/path/to/wildcard.crt
46+
export CODER_TLS_KEY_FILE=/path/to/wildcard.key
47+
```
48+
49+
See [TLS & Reverse Proxy](../setup/index.md#tls--reverse-proxy) for detailed configuration options.
50+
51+
#### Reverse Proxy with Let's Encrypt
52+
53+
Use a reverse proxy to handle TLS termination with automatic certificate management:
54+
55+
- [NGINX with Let's Encrypt](../../tutorials/reverse-proxy-nginx.md)
56+
- [Apache with Let's Encrypt](../../tutorials/reverse-proxy-apache.md)
57+
- [Caddy reverse proxy](../../tutorials/reverse-proxy-caddy.md)
58+
59+
### DNS Setup
60+
61+
You'll need to configure DNS to point wildcard subdomains to your Coder server:
62+
63+
> [!NOTE]
64+
> We do not recommend using a top-level-domain for Coder wildcard access
65+
> (for example `*.workspaces`), even on private networks with split-DNS. Some
66+
> browsers consider these "public" domains and will refuse Coder's cookies,
67+
> which are vital to the proper operation of this feature.
68+
69+
```text
70+
*.coder.example.com A <your-coder-server-ip>
71+
```
72+
73+
Or alternatively, using a CNAME record:
74+
75+
```text
76+
*.coder.example.com CNAME coder.example.com
77+
```
78+
79+
### Workspace Proxies
80+
81+
If you're using [workspace proxies](workspace-proxies.md) for geo-distributed teams, each proxy requires its own wildcard access URL configuration:
82+
83+
```bash
84+
# Main Coder server
85+
export CODER_WILDCARD_ACCESS_URL="*.coder.example.com"
86+
87+
# Sydney workspace proxy
88+
export CODER_WILDCARD_ACCESS_URL="*.sydney.coder.example.com"
89+
90+
# London workspace proxy
91+
export CODER_WILDCARD_ACCESS_URL="*.london.coder.example.com"
92+
```
93+
94+
Each proxy's wildcard domain must have corresponding DNS records:
95+
96+
```text
97+
*.sydney.coder.example.com A <sydney-proxy-ip>
98+
*.london.coder.example.com A <london-proxy-ip>
99+
```
100+
101+
## Template Configuration
102+
103+
In your Coder templates, enable subdomain applications using the `subdomain` parameter:
104+
105+
```hcl
106+
resource "coder_app" "code-server" {
107+
agent_id = coder_agent.main.id
108+
slug = "code-server"
109+
display_name = "VS Code"
110+
url = "http://localhost:8080"
111+
icon = "/icon/code.svg"
112+
subdomain = true
113+
share = "owner"
114+
}
115+
```
116+
117+
## Troubleshooting
118+
119+
### Applications not accessible
120+
121+
If workspace applications are not working:
122+
123+
1. Verify the `CODER_WILDCARD_ACCESS_URL` environment variable is configured correctly:
124+
- Check the deployment settings in the Coder dashboard (Settings > Deployment)
125+
- Ensure it matches your wildcard domain (e.g., `*.coder.example.com`)
126+
- Restart the Coder server if you made changes to the environment variable
127+
2. Check DNS resolution for wildcard subdomains:
128+
129+
```bash
130+
dig test.coder.example.com
131+
nslookup test.coder.example.com
132+
```
133+
134+
3. Ensure TLS certificates cover the wildcard domain
135+
4. Confirm template `coder_app` resources have `subdomain = true`
136+
137+
## See also
138+
139+
- [Workspace Proxies](workspace-proxies.md) - Improve performance for geo-distributed teams using wildcard URLs

‎docs/admin/setup/index.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,9 @@ coder server
3838

3939
## Wildcard access URL
4040

41+
> [!TIP]
42+
> Learn more about the [importance and benefits of wildcard access URLs](../networking/wildcard-access-url.md)
43+
4144
`CODER_WILDCARD_ACCESS_URL` is necessary for
4245
[port forwarding](../networking/port-forwarding.md#dashboard) via the dashboard
4346
or running [coder_apps](../templates/index.md) on an absolute path. Set this to

‎docs/manifest.json

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -770,6 +770,11 @@
770770
"path": "./admin/networking/high-availability.md",
771771
"state": ["premium"]
772772
},
773+
{
774+
"title": "Wildcard Access URL",
775+
"description": "Learn about wildcard access URL in Coder deployments",
776+
"path": "./admin/networking/wildcard-access-url.md"
777+
},
773778
{
774779
"title": "Troubleshooting",
775780
"description": "Troubleshoot networking issues in Coder",

0 commit comments

Comments
 (0)