Skip to content

Commit

Permalink
chore: add docs for sharing ports (#13136)
Browse files Browse the repository at this point in the history
Co-authored-by: kirby <kirby@coder.com>
Co-authored-by: Stephen Kirby <me@skirby.dev>
  • Loading branch information
3 people committed May 3, 2024
1 parent 34a3bdc commit a3c23ed
Show file tree
Hide file tree
Showing 5 changed files with 63 additions and 11 deletions.
Binary file added docs/images/networking/annotatedports.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/networking/listeningports.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/networking/portforwarddashboard.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/networking/portsharingmax.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
74 changes: 63 additions & 11 deletions docs/networking/port-forwarding.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,18 +60,9 @@ For more examples, see `coder port-forward --help`.
> name, agent name, workspace name and username exceed 63 characters in the
> hostname, port forwarding via the dashboard 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 apps inside the workspace
are listening on ports, and list them below the port input (this is only
supported on Windows and Linux workspace agents).

![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
One 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:
Expand Down Expand Up @@ -99,7 +90,68 @@ 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)
![Port forwarding from an app in the UI](../images/networking/portforwarddashboard.png)

## Accessing workspace ports

Another way to port forward in the dashboard is to use the "Open Ports" button
to specify an arbitrary port. Coder will also detect if apps inside the
workspace are listening on ports, and list them below the port input (this is
only supported on Windows and Linux workspace agents).

![Port forwarding in the UI](../images/networking/listeningports.png)

### Sharing ports

We allow developers to share ports as URLs, either with other authenticated
coder users or publicly. Using the open ports interface, developers can assign a
sharing levels that match our `coder_app`’s share option in
[Coder terraform provider](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/app#share).

- `owner` (Default): The implicit sharing level for all listening ports, only
visible to the workspace owner
- `authenticated`: Accessible by other authenticated Coder users on the same
deployment.
- `public`: Accessible by any user with the associated URL.

Once a port is shared at either `authenticated` or `public` levels, it will stay
pinned in the open ports UI for better accessibility regardless of whether or
not it is still accessible.

![Annotated port controls in the UI](../images/networking/annotatedports.png)

This can also be used to change the sharing level of `coder_app`s by entering
their port number in the shared ports UI. The `share` attribute of `coder_app`s
defined using the terraform provider can be overridden by sharing the port. The
sharing level is limited by the maximum level enforced by the template in
enterprise deployments, and not restricted in OSS deployments.

### Configure maximum port sharing level (enterprise)

Enterprise-licensed template admins can control the maximum port sharing level
for workspaces under a given template in the template settings. By default, the
maximum sharing level is set to `Owner`, meaning port sharing is disabled for
end-users. OSS deployments allow all workspaces to share ports at both the
`authenticated` and `public` levels.

![Max port sharing level in the UI](../images/networking/portsharingmax.png)

### Configuring port protocol

Both listening and shared ports can be configured to use either `HTTP` or
`HTTPS` to connect to the port. For listening ports the protocol selector
applies to any port you input or select from the menu. Shared ports have
protocol configuration for each shared port individually.

You can access any port on the workspace and can configure the port protocol
manually by appending a `s` to the port in the URL.

```
# Uses HTTP
https://33295--agent--workspace--user--apps.example.com/
# Uses HTTPS
https://33295s--agent--workspace--user--apps.example.com/
```

### Cross-origin resource sharing (CORS)

Expand Down

0 comments on commit a3c23ed

Please sign in to comment.