Skip to content

Commit 7e54413

Browse files
ammarioammario
authored
docs: add networking (#4030)
1 parent e9efb7e commit 7e54413

File tree

5 files changed

+126
-6
lines changed

5 files changed

+126
-6
lines changed

‎docs/ides.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -81,4 +81,4 @@ Web IDEs (code-server, JetBrains Projector, VNC, etc.) are defined in the templa
8181

8282
## Up next
8383

84-
- Learn about [Port Forwarding](./port-forwarding.md)
84+
- Learn about [Port Forwarding](./networking/port-forwarding.md)

‎docs/images/icons/port-forward.svg renamed to ‎docs/images/icons/networking.svg

File renamed without changes.

‎docs/manifest.json

Lines changed: 12 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@
3838
},
3939
{
4040
"title": "Docker",
41-
"description": "Install Coder with Docker / docker-compose/",
41+
"description": "Install Coder with Docker / docker-compose",
4242
"path": "./install/docker.md"
4343
},
4444
{
@@ -122,10 +122,17 @@
122122
]
123123
},
124124
{
125-
"title": "Port Forwarding",
126-
"description": "Learn how to forward ports in Coder",
127-
"path": "./port-forwarding.md",
128-
"icon_path": "./images/icons/port-forward.svg"
125+
"title": "Networking",
126+
"description": "Learn about networking in Coder",
127+
"path": "./networking.md",
128+
"icon_path": "./images/icons/networking.svg",
129+
"children": [
130+
{
131+
"title": "Port Forwarding",
132+
"description": "Learn how to forward ports in Coder",
133+
"path": "./networking/port-forwarding.md"
134+
}
135+
]
129136
},
130137
{
131138
"title": "Dotfiles",

‎docs/networking.md

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
# Networking
2+
3+
Coder's network topology has three types of nodes:
4+
workspaces, coder servers, and users.
5+
6+
The coder server must have an inbound address reachable by users and workspaces,
7+
but otherwise, all topologies _just work_ with Coder.
8+
9+
When possible, we establish direct connections between users and workspaces.
10+
Direct connections are as fast as connecting to the workspace outside of Coder.
11+
When NAT traversal fails, connections are relayed through the coder server.
12+
All user <-> workspace connections are end-to-end encrypted.
13+
14+
[Tailscale's open source](https://tailscale.com) backs our networking logic.
15+
16+
## coder server
17+
18+
Workspaces connect to the coder server via the server's external address,
19+
set via [`ACCESS_URL`](./admin/configure#access-url). There must not be a
20+
NAT between workspaces and coder server.
21+
22+
Users connect to the coder server's dashboard and API through its `ACCESS_URL`
23+
as well. There must not be a NAT between users and the coder server.
24+
25+
## Web Apps
26+
27+
The coder servers relays dashboard-initiated connections between the user and
28+
the workspace. Web terminal <-> workspace connections are an exception and may be direct.
29+
30+
In general, [port forwarded](./networking/port-forwarding.md) web apps are
31+
faster than dashboard-accessed web apps.
32+
33+
## 🌎 Geo-distribution
34+
35+
### Direct connections
36+
37+
Direct connections are a straight line between the user and workspace, so there
38+
is no special geo-distribution configuration. To speed up direct connections,
39+
move the user and workspace closer together.
40+
41+
### Relayed connections
42+
43+
Tailscale has graciously allowed us to use
44+
[their global DERP relays](https://tailscale.com/kb/1118/custom-derp-servers/#what-are-derp-servers).
45+
46+
You can launch `coder server` with Tailscale's DERPs like so:
47+
48+
```bash
49+
$ coder server --derp-config-url https://controlplane.tailscale.com/derpmap/default
50+
```
51+
52+
#### Custom Relays
53+
54+
If you run Coder in air-gap mode or want lower latency than what Tailscale offers,
55+
you may run custom DERP servers. Refer to
56+
[Tailscale's documentation](https://tailscale.com/kb/1118/custom-derp-servers/#why-run-your-own-derp-server)
57+
to learn how to set them up.
58+
59+
After you have custom DERP servers, you can launch Coder with them like so:
60+
61+
```json
62+
# derpmap.json
63+
{
64+
"Regions": {
65+
"1": {
66+
"RegionID": 1,
67+
"RegionCode": "myderp",
68+
"RegionName": "My DERP",
69+
"Nodes": [
70+
{
71+
"Name": "1",
72+
"RegionID": 1,
73+
"HostName": "your-hostname.com"
74+
}
75+
]
76+
}
77+
}
78+
}
79+
```
80+
81+
```bash
82+
$ coder server --derp-config-path derpmap.json
83+
```
84+
85+
### Dashboard connections
86+
87+
The dashboard (and web apps opened through the dashboard) are served from the
88+
coder server, so they can only be geo-distributed with High Availability mode in
89+
our Enterprise Edition. [Reach out to sales](mailto:sales@coder.com) to learn more.
90+
91+
## Troubleshooting
92+
93+
The `coder speedtest <workspace>` command measures user <-> workspace throughput.
94+
E.g.:
95+
96+
```
97+
$ coder speedtest dev
98+
29ms via coder
99+
Starting a 5s download test...
100+
INTERVAL TRANSFER BANDWIDTH
101+
0.00-1.00 sec 630.7840 MBits 630.7404 Mbits/sec
102+
1.00-2.00 sec 913.9200 MBits 913.8106 Mbits/sec
103+
2.00-3.00 sec 943.1040 MBits 943.0399 Mbits/sec
104+
3.00-4.00 sec 933.3760 MBits 933.2143 Mbits/sec
105+
4.00-5.00 sec 848.8960 MBits 848.7019 Mbits/sec
106+
5.00-5.02 sec 13.5680 MBits 828.8189 Mbits/sec
107+
----------------------------------------------------
108+
0.00-5.02 sec 4283.6480 MBits 853.8217 Mbits/sec
109+
```
110+
111+
## Up next
112+
113+
- Learn about [Port Forwarding](./networking/port-forwarding.md)

‎docs/port-forwarding.md renamed to ‎docs/networking/port-forwarding.md

File renamed without changes.

0 commit comments

Comments
 (0)