diff --git a/docs/ides.md b/docs/ides.md index 04fc55e315..1937c7c946 100644 --- a/docs/ides.md +++ b/docs/ides.md @@ -81,4 +81,4 @@ Web IDEs (code-server, JetBrains Projector, VNC, etc.) are defined in the templa ## Up next -- Learn about [Port Forwarding](./port-forwarding.md) +- Learn about [Port Forwarding](./networking/port-forwarding.md) diff --git a/docs/images/icons/port-forward.svg b/docs/images/icons/networking.svg similarity index 100% rename from docs/images/icons/port-forward.svg rename to docs/images/icons/networking.svg diff --git a/docs/manifest.json b/docs/manifest.json index 3441d8bab6..6c3d4ab1ea 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -38,7 +38,7 @@ }, { "title": "Docker", - "description": "Install Coder with Docker / docker-compose/", + "description": "Install Coder with Docker / docker-compose", "path": "./install/docker.md" }, { @@ -122,10 +122,17 @@ ] }, { - "title": "Port Forwarding", - "description": "Learn how to forward ports in Coder", - "path": "./port-forwarding.md", - "icon_path": "./images/icons/port-forward.svg" + "title": "Networking", + "description": "Learn about networking in Coder", + "path": "./networking.md", + "icon_path": "./images/icons/networking.svg", + "children": [ + { + "title": "Port Forwarding", + "description": "Learn how to forward ports in Coder", + "path": "./networking/port-forwarding.md" + } + ] }, { "title": "Dotfiles", diff --git a/docs/networking.md b/docs/networking.md new file mode 100644 index 0000000000..fc16d75007 --- /dev/null +++ b/docs/networking.md @@ -0,0 +1,113 @@ +# Networking + +Coder's network topology has three types of nodes: +workspaces, coder servers, and users. + +The coder server must have an inbound address reachable by users and workspaces, +but otherwise, all topologies _just work_ with Coder. + +When possible, we establish direct connections between users and workspaces. +Direct connections are as fast as connecting to the workspace outside of Coder. +When NAT traversal fails, connections are relayed through the coder server. +All user <-> workspace connections are end-to-end encrypted. + +[Tailscale's open source](https://tailscale.com) backs our networking logic. + +## coder server + +Workspaces connect to the coder server via the server's external address, +set via [`ACCESS_URL`](./admin/configure#access-url). There must not be a +NAT between workspaces and coder server. + +Users connect to the coder server's dashboard and API through its `ACCESS_URL` +as well. There must not be a NAT between users and the coder server. + +## Web Apps + +The coder servers relays dashboard-initiated connections between the user and +the workspace. Web terminal <-> workspace connections are an exception and may be direct. + +In general, [port forwarded](./networking/port-forwarding.md) web apps are +faster than dashboard-accessed web apps. + +## 🌎 Geo-distribution + +### Direct connections + +Direct connections are a straight line between the user and workspace, so there +is no special geo-distribution configuration. To speed up direct connections, +move the user and workspace closer together. + +### Relayed connections + +Tailscale has graciously allowed us to use +[their global DERP relays](https://tailscale.com/kb/1118/custom-derp-servers/#what-are-derp-servers). + +You can launch `coder server` with Tailscale's DERPs like so: + +```bash +$ coder server --derp-config-url https://controlplane.tailscale.com/derpmap/default +``` + +#### Custom Relays + +If you run Coder in air-gap mode or want lower latency than what Tailscale offers, +you may run custom DERP servers. Refer to +[Tailscale's documentation](https://tailscale.com/kb/1118/custom-derp-servers/#why-run-your-own-derp-server) +to learn how to set them up. + +After you have custom DERP servers, you can launch Coder with them like so: + +```json +# derpmap.json +{ + "Regions": { + "1": { + "RegionID": 1, + "RegionCode": "myderp", + "RegionName": "My DERP", + "Nodes": [ + { + "Name": "1", + "RegionID": 1, + "HostName": "your-hostname.com" + } + ] + } + } +} +``` + +```bash +$ coder server --derp-config-path derpmap.json +``` + +### Dashboard connections + +The dashboard (and web apps opened through the dashboard) are served from the +coder server, so they can only be geo-distributed with High Availability mode in +our Enterprise Edition. [Reach out to sales](mailto:sales@coder.com) to learn more. + +## Troubleshooting + +The `coder speedtest ` command measures user <-> workspace throughput. +E.g.: + +``` +$ coder speedtest dev +29ms via coder +Starting a 5s download test... +INTERVAL TRANSFER BANDWIDTH +0.00-1.00 sec 630.7840 MBits 630.7404 Mbits/sec +1.00-2.00 sec 913.9200 MBits 913.8106 Mbits/sec +2.00-3.00 sec 943.1040 MBits 943.0399 Mbits/sec +3.00-4.00 sec 933.3760 MBits 933.2143 Mbits/sec +4.00-5.00 sec 848.8960 MBits 848.7019 Mbits/sec +5.00-5.02 sec 13.5680 MBits 828.8189 Mbits/sec +---------------------------------------------------- +0.00-5.02 sec 4283.6480 MBits 853.8217 Mbits/sec +``` + +## Up next + +- Learn about [Port Forwarding](./networking/port-forwarding.md) diff --git a/docs/port-forwarding.md b/docs/networking/port-forwarding.md similarity index 100% rename from docs/port-forwarding.md rename to docs/networking/port-forwarding.md