opensource/coder
3
0
Fork 0
mirror of https://github.com/coder/coder.git synced 2026-09-24 15:04:27 +08:00
Code Issues Packages Projects Releases Wiki Activity

chore(docs): update docs for correct use of shell and console and enforce linewidth (#9245)

Browse Source
This commit is contained in:
Muhammad Atif Ali
2023-08-23 12:27:57 +03:00
committed by GitHub
parent ed2b1236c0
commit d37f6d80f7
96 changed files with 2838 additions and 1457 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/networking/index.md
+31 -22
View File
@@ -1,29 +1,30 @@
# Networking
Coder's network topology has three types of nodes:
workspaces, coder servers, and users.
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.
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.md#access-url). There must not be a
NAT between workspaces and coder server.
Workspaces connect to the coder server via the server's external address, set
via [`ACCESS_URL`](../admin/configure.md#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.
Template admins can overwrite the site-wide access URL at the template level by
leveraging the `url` argument when [defining the Coder provider](https://registry.terraform.io/providers/coder/coder/latest/docs#url):
leveraging the `url` argument when
[defining the Coder provider](https://registry.terraform.io/providers/coder/coder/latest/docs#url):
```terraform
provider "coder" {
@@ -31,16 +32,17 @@ provider "coder" {
}
```
This is useful when debugging connectivity issues between the workspace agent and
the Coder server.
This is useful when debugging connectivity issues between the workspace agent
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.
the workspace. Web terminal <-> workspace connections are an exception and may
be direct.
In general, [port forwarded](./port-forwarding.md) web apps are
faster than dashboard-accessed web apps.
In general, [port forwarded](./port-forwarding.md) web apps are faster than
dashboard-accessed web apps.
## 🌎 Geo-distribution
@@ -50,16 +52,20 @@ 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.
If a direct connection is not available (e.g. client or server is behind NAT), Coder
will use a relayed connection. By default, [Coder uses Google's public STUN server](../cli/server.md#--derp-server-stun-addresses), but
this can be disabled or changed for [offline deployments](../install/offline.md).
If a direct connection is not available (e.g. client or server is behind NAT),
Coder will use a relayed connection. By default,
[Coder uses Google's public STUN server](../cli/server.md#--derp-server-stun-addresses),
but this can be disabled or changed for
[offline deployments](../install/offline.md).
### Relayed connections
By default, your Coder server also runs a built-in DERP relay which can be used for both public and [offline deployments](../install/offline.md).
By default, your Coder server also runs a built-in DERP relay which can be used
for both public and [offline deployments](../install/offline.md).
However, 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:
[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
@@ -67,7 +73,9 @@ $ coder server --derp-config-url https://controlplane.tailscale.com/derpmap/defa
#### Custom Relays
If you want lower latency than what Tailscale offers or want additional DERP relays for offline deployments, 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)
If you want lower latency than what Tailscale offers or want additional DERP
relays for offline deployments, 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:
@@ -109,7 +117,8 @@ Some Coder deployments require that all access is through the browser to comply
with security policies. In these cases, pass the `--browser-only` flag to
`coder server` or set `CODER_BROWSER_ONLY=true`.
With browser-only connections, developers can only connect to their workspaces via the web terminal and [web IDEs](../ides/web-ides.md).
With browser-only connections, developers can only connect to their workspaces
via the web terminal and [web IDEs](../ides/web-ides.md).
## Troubleshooting
@@ -128,8 +137,8 @@ pong from my-workspace proxied via DERP(Denver) in 90ms
2023-06-21 17:50:22.504 [debu] wgengine: wg: [v2] Device closed
```
The `coder speedtest <workspace>` command measures user <-> workspace throughput.
E.g.:
The `coder speedtest <workspace>` command measures user <-> workspace
throughput. E.g.:
```
$ coder speedtest dev
docs/networking/port-forwarding.md
+33 -18
View File
@@ -1,8 +1,8 @@
# Port Forwarding
Port forwarding lets developers securely access processes on their Coder
workspace from a local machine. A common use case is testing web
applications in a browser.
workspace from a local machine. A common use case is testing web applications in
a browser.
There are three ways to forward ports in Coder:
@@ -14,9 +14,9 @@ The `coder port-forward` command is generally more performant.
## The `coder port-forward` command
This command can be used to forward TCP or UDP ports from the remote
workspace so they can be accessed locally. Both the TCP and UDP command
line flags (`--tcp` and `--udp`) can be given once or multiple times.
This command can be used to forward TCP or UDP ports from the remote workspace
so they can be accessed locally. Both the TCP and UDP command line flags
(`--tcp` and `--udp`) can be given once or multiple times.
The supported syntax variations for the `--tcp` and `--udp` flag are:
@@ -33,8 +33,8 @@ Forward the remote TCP port `8080` to local port `8000`:
coder port-forward myworkspace --tcp 8000:8080
```
Forward the remote TCP port `3000` and all ports from `9990` to `9999`
to their respective local ports.
Forward the remote TCP port `3000` and all ports from `9990` to `9999` to their
respective local ports.
```console
coder port-forward myworkspace --tcp 3000,9990-9999
@@ -46,20 +46,27 @@ For more examples, see `coder port-forward --help`.
> To enable port forwarding via the dashboard, Coder must be configured with a
> [wildcard access URL](../admin/configure.md#wildcard-access-url). If an access
> URL is not specified, Coder will create [a publicly accessible URL](../admin/configure.md#tunnel)
> to reverse proxy the deployment, and port forwarding will work. There is a
> known limitation where if the port forwarding URL length is greater than 63
> characters, port forwarding will not work.
> URL is not specified, Coder will create
> [a publicly accessible URL](../admin/configure.md#tunnel) to reverse proxy the
> deployment, and port forwarding will work. There is a known limitation where
> if the port forwarding URL length is greater than 63 characters, port
> forwarding will not work.
### From an arbitrary port
One way to port forward in the dashboard is to use the "Port forward" button to specify an arbitrary port. Coder will also detect if processes are running, and will list them below the port picklist to click an open the running processes in the browser.
One way to port forward in the dashboard is to use the "Port forward" button to
specify an arbitrary port. Coder will also detect if processes are running, and
will list them below the port picklist to click an open the running processes in
the browser.
![Port forwarding in the UI](../images/port-forward-dashboard.png)
### From an coder_app resource
Another way to port forward is to configure a `coder_app` resource in the workspace's template. This approach shows a visual application icon in the dashboard. See the following `coder_app` example for a Node React app and note the `subdomain` and `share` settings:
Another way to port forward is to configure a `coder_app` resource in the
workspace's template. This approach shows a visual application icon in the
dashboard. See the following `coder_app` example for a Node React app and note
the `subdomain` and `share` settings:
```hcl
# node app
@@ -80,7 +87,9 @@ resource "coder_app" "node-react-app" {
}
```
Valid `share` values include `owner` - private to the user, `authenticated` - accessible by any user authenticated to the Coder deployment, and `public` - accessible by users outside of the Coder deployment.
Valid `share` values include `owner` - private to the user, `authenticated` -
accessible by any user authenticated to the Coder deployment, and `public` -
accessible by users outside of the Coder deployment.
![Port forwarding from an app in the UI](../images/coderapp-port-forward.png)
@@ -100,7 +109,12 @@ must include credentials (set `credentials: "include"` if using `fetch`) or the
requests cannot be authenticated and you will see an error resembling the
following:
> Access to fetch at 'https://coder.example.com/api/v2/applications/auth-redirect' from origin 'https://8000--dev--user--apps.coder.example.com' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource. If an opaque response serves your needs, set the request's mode to 'no-cors' to fetch the resource with CORS disabled.
> Access to fetch at
> 'https://coder.example.com/api/v2/applications/auth-redirect' from origin
> 'https://8000--dev--user--apps.coder.example.com' has been blocked by CORS
> policy: No 'Access-Control-Allow-Origin' header is present on the requested
> resource. If an opaque response serves your needs, set the request's mode to
> 'no-cors' to fetch the resource with CORS disabled.
#### Headers
@@ -197,11 +211,12 @@ configurable by either admins or users.
## SSH
First, [configure SSH](../ides.md#ssh-configuration) on your
local machine. Then, use `ssh` to forward like so:
First, [configure SSH](../ides.md#ssh-configuration) on your local machine.
Then, use `ssh` to forward like so:
```console
ssh -L 8080:localhost:8000 coder.myworkspace
```
You can read more on SSH port forwarding [here](https://www.ssh.com/academy/ssh/tunneling/example).
You can read more on SSH port forwarding
[here](https://www.ssh.com/academy/ssh/tunneling/example).