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

docs: restructure docs (#14421)

Browse Source 
Closes #13434 
Supersedes #14182

---------

Co-authored-by: Ethan <39577870+ethanndickson@users.noreply.github.com>
Co-authored-by: Ethan Dickson <ethan@coder.com>
Co-authored-by: Ben Potter <ben@coder.com>
Co-authored-by: Stephen Kirby <58410745+stirby@users.noreply.github.com>
Co-authored-by: Stephen Kirby <me@skirby.dev>
Co-authored-by: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com>
Co-authored-by: Edward Angert <EdwardAngert@users.noreply.github.com>
This commit is contained in:
Muhammad Atif Ali
2024-10-05 10:52:04 -05:00
committed by GitHub
co-authored by Ethan Ethan Dickson Ben Potter Stephen Kirby Stephen Kirby EdwardAngert Edward Angert
parent 288df75686
commit 419eba5fb6
298 changed files with 5009 additions and 3889 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/user-guides/workspace-access/emacs-tramp.md
+160
View File
@@ -0,0 +1,160 @@
# Emacs TRAMP
[Emacs TRAMP](https://www.emacswiki.org/emacs/TrampMode) is a method of running
editing operations on a remote server.
## Connecting To A Workspace
To connect to your workspace first run:
```
coder config-ssh
```
Then you can connect to your workspace by its name in the format:
`coder.<WORKSPACE NAME>`.
In Emacs type `C-x d` and then input: `/-:coder.<WORKSPACE NAME>:` and hit
enter. This will open up Dired on the workspace's home directory.
### Using SSH
By default Emacs TRAMP is setup to use SCP to access files on the Coder
workspace instance. However you might want to use SSH if you have a jumpbox or
some other complex network setup.
To do so set the following in your Emacs `init.el` file:
```lisp
(setq tramp-default-method "ssh")
```
Then when you access the workspace instance via `/-:coder.<WORKSPACE NAME>`
Emacs will use SSH. Setting `tramp-default-method` will also tell `ansi-term`
mode the correct way to access the remote when directory tracking.
## Directory Tracking
### ansi-term
If you run your terminal in Emacs via `ansi-term` then you might run into a
problem where while SSH-ed into a workspace Emacs will not change its
`default-directory` to open files in the directory your shell is in.
To fix this:
1. In your workspace Terraform template be sure to add the following:
```tf
data "coder_workspace" "me" {
}
resource "coder_agent" "main" {
# ...
env = {
name = "CODER_WORKSPACE_NAME"
value = data.coder_workspace.me.name
}
}
```
2. Next in the shell profile file on the workspace (ex., `~/.bashrc` for Bash
and `~/.zshrc` for Zsh) add the following:
```bash
ansi_term_announce_host() {
printf '\033AnSiTh %s\n' "coder.$CODER_WORKSPACE_NAME"
}
ansi_term_announce_user() {
printf '\033AnSiTu %s\n' "$USER"
}
ansi_term_announce_pwd() {
printf '\033AnSiTc %s\n' "$PWD"
}
ansi_term_announce() {
ansi_term_announce_host
ansi_term_announce_user
ansi_term_announce_pwd
}
cd() { command cd "$@"; ansi_term_announce_pwd; }
pushd() { command pushd "$@"; ansi_term_announce_pwd; }
popd() { command popd "$@"; ansi_term_announce_pwd; }
ansi_term_announce
```
Ansi Term expects the terminal running inside of it to send escape codes to
inform Emacs of the hostname, user, and working directory. The above code
sends these escape codes and associated data whenever the terminal logs in
and whenever the directory changes.
### eshell
The `eshell` mode will perform directory tracking by default, no additional
configuration is needed.
## Language Servers (Code Completion)
If you use [`lsp-mode`](https://emacs-lsp.github.io/lsp-mode) for code
intelligence and completion some additional configuration is required.
In your Emacs `init.el` file you must register a LSP client and tell `lsp-mode`
how to find it on the remote machine using the `lsp-register-client` function.
For each LSP server you want to use in your workspace add the following:
```lisp
(lsp-register-client (make-lsp-client :new-connection (lsp-tramp-connection "<LSP SERVER BINARY>")
:major-modes '(<LANGUAGE MODE>)
:remote? t
:server-id '<LANGUAGE SERVER ID>))
```
This tells `lsp-mode` to look for a language server binary named
`<LSP SERVER BINARY>` for use in `<LANGUAGE MODE>` on a machine named
`coder.<WORKSPACE NAME>`. Be sure to replace the values between angle brackets:
- `<LSP SERVER BINARY>` : The name of the language server binary, without any
path components. For example to use the Deno Javascript language server use
the value `deno`.
- `<LANGUAGE MODE>`: The name of the Emacs major mode for which the language
server should be used. For example to enable the language server for
Javascript development use the value `web-mode`.
- `<LANGUAGE SERVER ID>`: This is just the name that `lsp-mode` will use to
refer to this language server. If you are ever looking for output buffers or
files they may have this name in them.
Calling the `lsp-register-client` function will tell `lsp-mode` the name of the
LSP server binary. However this binary must be accessible via the path. If the
language server binary is not in the path you must modify `tramp-remote-path` so
that `lsp-mode` knows in what directories to look for the LSP server. To do this
use TRAMP's connection profiles functionality. These connection profiles let you
customize variables depending on what machine you are connected to. Add the
following to your `init.el`:
```lisp
(connection-local-set-profile-variables 'remote-path-lsp-servers
'((tramp-remote-path . ("<PATH TO ADD>" tramp-default-remote-path))))
(connection-local-set-profiles '(:machine "coder.<WORKSPACE NAME>") 'remote-path-lsp-servers)
```
The `connection-local-set-profile-variables` function creates a new connection
profile by the name `remote-path-lsp-servers`. The
`connection-local-set-profiles` then indicates this `remote-path-lsp-servers`
connection profile should be used when connecting to a server named
`coder.<WORKSPACE NAME>`. Be sure to replace `<PATH TO ADD>` with the directory
in which a LSP server is present.
TRAMP and `lsp-mode` are fickle friends, sometimes there is weird behavior. If
you find that language servers are hanging in the `starting` state then
[it might be helpful](https://github.com/emacs-lsp/lsp-mode/issues/2709#issuecomment-800868919)
to set the `lsp-log-io` variable to `t`.
More details on configuring `lsp-mode` for TRAMP can be found
[in the `lsp-mode` documentation](https://emacs-lsp.github.io/lsp-mode/page/remote/).
The
[TRAMP `tramp-remote-path` documentation](https://www.gnu.org/software/emacs/manual/html_node/tramp/Remote-programs.html#Remote-programs)
contains more examples and details of connection profiles.
docs/user-guides/workspace-access/filebrowser.md
+7
View File
@@ -0,0 +1,7 @@
# File Browser
File Browser is a file manager for the web that can be used to upload, download,
and view files in your workspace. A template administrator can add it by
following the
[Extending Templates](../../admin/templates/extending-templates/web-ides.md#file-browser)
guide. ![File Browser](../../images/file-browser.png)
docs/user-guides/workspace-access/index.md
+137
View File
@@ -0,0 +1,137 @@
# Access your workspace
There are many ways to connect to your workspace, the options are only limited
by the template configuration.
> Deployment operators can learn more about different types of workspace
> connections and performance in our
> [networking docs](../../admin/infrastructure/index.md).
You can see the primary methods of connecting to your workspace in the workspace
dashboard.
![Workspace View](../../images/user-guides/workspace-view-connection-annotated.png)
## Terminal
The terminal is implicitly enabled in Coder and allows you to access your
workspace through the shell environment set by your template.
![Terminal Access](../../images/user-guides/terminal-access.png)
## SSH
### Through with the CLI
Coder will use the optimal path for an SSH connection (determined by your
deployment's [networking configuration](../../admin/infrastructure/index.md))
when using the CLI:
```console
coder ssh my-workspace
```
Or, you can configure plain SSH on your client below.
### Configure SSH
Coder generates [SSH key pairs](../../admin/security/secrets.md#ssh-keys) for
each user to simplify the setup process.
> Before proceeding, run `coder login <accessURL>` if you haven't already to
> authenticate the CLI with the web UI and your workspaces.
To access Coder via SSH, run the following in the terminal:
```console
coder config-ssh
```
> Run `coder config-ssh --dry-run` if you'd like to see the changes that will be
> made before proceeding.
Confirm that you want to continue by typing **yes** and pressing enter. If
successful, you'll see the following message:
```console
You should now be able to ssh into your workspace.
For example, try running:
$ ssh coder.<workspaceName>
```
Your workspace is now accessible via `ssh coder.<workspace_name>` (e.g.,
`ssh coder.myEnv` if your workspace is named `myEnv`).
## Visual Studio Code
You can develop in your Coder workspace remotely with
[VSCode](https://code.visualstudio.com/download). We support connecting with the
desktop client and VSCode in the browser with [code-server](#code-server).
![Demo](https://github.com/coder/vscode-coder/raw/main/demo.gif?raw=true)
Read more details on [using VSCode in your workspace](./vscode.md).
## JetBrains IDEs
We support JetBrains IDEs using
[Gateway](https://www.jetbrains.com/remote-development/gateway/). The following
IDEs are supported for remote development:
- IntelliJ IDEA
- CLion
- GoLand
- PyCharm
- Rider
- RubyMine
- WebStorm
- [JetBrains Fleet](./jetbrains.md#jetbrains-fleet)
Read our [docs on JetBrains Gateway](./jetbrains.md) for more information on
connecting your JetBrains IDEs.
## code-server
[code-server](https://github.com/coder/code-server) is our supported method of
running VS Code in the web browser. You can read more in our
[documentation for code-server](https://coder.com/docs/code-server/latest).
![code-server in a workspace](../../images/code-server-ide.png)
## Other Web IDEs
We support a variety of other browser IDEs and tools to interact with your
workspace. Each of these can be configured by your template admin using our
[Web IDE guides](../../admin/templates/extending-templates/web-ides.md).
Supported IDEs:
- VS Code Web
- JupyterLab
- RStudio
- Airflow
- File Browser
Our [Module Registry](https://registry.coder.com/modules) also hosts a variety
of tools for extending the capability of your workspace. If you have a request
for a new IDE or tool, please file an issue in our
[Modules repo](https://github.com/coder/modules/issues).
## Ports and Port forwarding
You can manage listening ports on your workspace page through with the listening
ports window in the dashboard. These ports are often used to run internal
services or preview environments.
You can also [share ports](./port-forwarding.md#sharing-ports) with other users,
or [port-forward](./port-forwarding.md#the-coder-port-forward-command) through
the CLI with `coder port forward`. Read more in the
[docs on workspace ports](./port-forwarding.md).
![Open Ports window](../../images/networking/listeningports.png)
## Remote Desktops
Coder also supports connecting with an RDP solution, see our
[RDP guide](./remote-desktops.md) for details.
docs/user-guides/workspace-access/jetbrains.md
+394
View File
@@ -0,0 +1,394 @@
# JetBrains IDEs
We support JetBrains IDEs using
[Gateway](https://www.jetbrains.com/remote-development/gateway/). The following
IDEs are supported for remote development:
- IntelliJ IDEA
- CLion
- GoLand
- PyCharm
- Rider
- RubyMine
- WebStorm
- [JetBrains Fleet](#jetbrains-fleet)
## JetBrains Gateway
JetBrains Gateway is a compact desktop app that allows you to work remotely with
a JetBrains IDE without even downloading one. Visit the
[JetBrains website](https://www.jetbrains.com/remote-development/gateway/) to
learn more about Gateway.
Gateway can connect to a Coder workspace by using Coder's Gateway plugin or
manually setting up an SSH connection.
### How to use the plugin
> If you experience problems, please
> [create a GitHub issue](https://github.com/coder/coder/issues) or share in
> [our Discord channel](https://discord.gg/coder).
1. [Install Gateway](https://www.jetbrains.com/help/idea/jetbrains-gateway.html)
and open the application.
1. Under **Install More Providers**, find the Coder icon and click **Install**
to install the Coder plugin.
1. After Gateway installs the plugin, it will appear in the **Run the IDE
Remotely** section.
Click **Connect to Coder** to launch the plugin:
![Gateway Connect to Coder](../../images/gateway/plugin-connect-to-coder.png)
1. Enter your Coder deployment'ssetup/index.md
[Access Url](../../admin/setup/index.md#access-url) and click **Connect**.
Gateway opens your Coder deployment's `cli-auth` page with a session token.
Click the copy button, paste the session token in the Gateway **Session
Token** window, then click **OK**:
![Gateway Session Token](../../images/gateway/plugin-session-token.png)
1. To create a new workspace:
Click the <kbd>+</kbd> icon to open a browser and go to the templates page in
your Coder deployment to create a workspace.
1. If a workspace already exists but is stopped, select the workspace from the
list, then click the green arrow to start the workspace.
1. When the workspace status is **Running**, click **Select IDE and Project**:
![Gateway IDE List](../../images/gateway/plugin-select-ide.png)
1. Select the JetBrains IDE for your project and the project directory then
click **Start IDE and connect**:
![Gateway Select IDE](../../images/gateway/plugin-ide-list.png)
Gateway connects using the IDE you selected:
![Gateway IDE Opened](../../images/gateway/gateway-intellij-opened.png)
> Note the JetBrains IDE is remotely installed into
> `~/.cache/JetBrains/RemoteDev/dist`
### Update a Coder plugin version
1. Click the gear icon at the bottom left of the Gateway home screen and then
"Settings"
1. In the **Marketplace** tab within Plugins, enter Coder and if a newer plugin
release is available, click **Update** then **OK**:
![Gateway Settings and Marketplace](../../images/gateway/plugin-settings-marketplace.png)
### Configuring the Gateway plugin to use internal certificates
When attempting to connect to a Coder deployment that uses internally signed
certificates, you may receive the following error in Gateway:
```console
Failed to configure connection to https://coder.internal.enterprise/: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
```
To resolve this issue, you will need to add Coder's certificate to the Java
trust store present on your local machine. Here is the default location of the
trust store for each OS:
```console
# Linux
<Gateway installation directory>/jbr/lib/security/cacerts
# macOS
<Gateway installation directory>/jbr/lib/security/cacerts
/Library/Application Support/JetBrains/Toolbox/apps/JetBrainsGateway/ch-0/<app-id>/JetBrains Gateway.app/Contents/jbr/Contents/Home/lib/security/cacerts # Path for Toolbox installation
# Windows
C:\Program Files (x86)\<Gateway installation directory>\jre\lib\security\cacerts
%USERPROFILE%\AppData\Local\JetBrains\Toolbox\bin\jre\lib\security\cacerts # Path for Toolbox installation
```
To add the certificate to the keystore, you can use the `keytool` utility that
ships with Java:
```console
keytool -import -alias coder -file <certificate> -keystore /path/to/trust/store
```
You can use `keytool` that ships with the JetBrains Gateway installation.
Windows example:
```powershell
& 'C:\Program Files\JetBrains\JetBrains Gateway <version>/jbr/bin/keytool.exe' 'C:\Program Files\JetBrains\JetBrains Gateway <version>/jre/lib/security/cacerts' -import -alias coder -file <cert>
# command for Toolbox installation
& '%USERPROFILE%\AppData\Local\JetBrains\Toolbox\apps\Gateway\ch-0\<VERSION>\jbr\bin\keytool.exe' '%USERPROFILE%\AppData\Local\JetBrains\Toolbox\bin\jre\lib\security\cacerts' -import -alias coder -file <cert>
```
macOS example:
```shell
keytool -import -alias coder -file cacert.pem -keystore /Applications/JetBrains\ Gateway.app/Contents/jbr/Contents/Home/lib/security/cacerts
```
## Manually Configuring A JetBrains Gateway Connection
> This is in lieu of using Coder's Gateway plugin which automatically performs
> these steps.
1. [Install Gateway](https://www.jetbrains.com/help/idea/jetbrains-gateway.html).
1. [Configure the `coder` CLI](../../user-guides/workspace-access/index.md#configure-ssh).
1. Open Gateway, make sure **SSH** is selected under **Remote Development**.
1. Click **New Connection**:
![Gateway Home](../../images/gateway/gateway-home.png)
1. In the resulting dialog, click the gear icon to the right of **Connection**:
![Gateway New Connection](../../images/gateway/gateway-new-connection.png)
1. Click <kbd>+</kbd> to add a new SSH connection:
![Gateway Add Connection](../../images/gateway/gateway-add-ssh-configuration.png)
1. For the Host, enter `coder.<workspace name>`
1. For the Port, enter `22` (this is ignored by Coder)
1. For the Username, enter your workspace username.
1. For the Authentication Type, select **OpenSSH config and authentication
agent**.
1. Make sure the checkbox for **Parse config file ~/.ssh/config** is checked.
1. Click **Test Connection** to validate these settings.
1. Click **OK**:
![Gateway SSH Configuration](../../images/gateway/gateway-create-ssh-configuration.png)
1. Select the connection you just added:
![Gateway Welcome](../../images/gateway/gateway-welcome.png)
1. Click **Check Connection and Continue**:
![Gateway Continue](../../images/gateway/gateway-continue.png)
1. Select the JetBrains IDE for your project and the project directory. SSH into
your server to create a directory or check out code if you haven't already.
![Gateway Choose IDE](../../images/gateway/gateway-choose-ide.png)
> Note the JetBrains IDE is remotely installed into
> `~/. cache/JetBrains/RemoteDev/dist`
1. Click **Download and Start IDE** to connect.
![Gateway IDE Opened](../../images/gateway/gateway-intellij-opened.png)
## Using an existing JetBrains installation in the workspace
If you would like to use an existing JetBrains IDE in a Coder workspace (or you
are air-gapped, and cannot reach jetbrains.com), run the following script in the
JetBrains IDE directory to point the default Gateway directory to the IDE
directory. This step must be done before configuring Gateway.
```shell
cd /opt/idea/bin
./remote-dev-server.sh registerBackendLocationForGateway
```
> Gateway only works with paid versions of JetBrains IDEs so the script will not
> be located in the `bin` directory of JetBrains Community editions.
[Here is the JetBrains article](https://www.jetbrains.com/help/idea/remote-development-troubleshooting.html#setup:~:text=Can%20I%20point%20Remote%20Development%20to%20an%20existing%20IDE%20on%20my%20remote%20server%3F%20Is%20it%20possible%20to%20install%20IDE%20manually%3F)
explaining this IDE specification.
## JetBrains Gateway in an offline environment
In networks that restrict access to the internet, you will need to leverage the
JetBrains Client Installer to download and save the IDE clients locally. Please
see the
[JetBrains documentation for more information](https://www.jetbrains.com/help/idea/fully-offline-mode.html).
### Configuration Steps
The Coder team built a POC of the JetBrains Gateway Offline Mode solution. Here
are the steps we took (and "gotchas"):
### 1. Deploy the server and install the Client Downloader
We deployed a simple Ubuntu VM and installed the JetBrains Client Downloader
binary. Note that the server must be a Linux-based distribution.
```shell
wget https://download.jetbrains.com/idea/code-with-me/backend/jetbrains-clients-downloader-linux-x86_64-1867.tar.gz && \
tar -xzvf jetbrains-clients-downloader-linux-x86_64-1867.tar.gz
```
### 2. Install backends and clients
JetBrains Gateway requires both a backend to be installed on the remote host
(your Coder workspace) and a client to be installed on your local machine. You
can host both on the server in this example.
See here for the full
[JetBrains product list and builds](https://data.services.jetbrains.com/products).
Below is the full list of supported `--platforms-filter` values:
```console
windows-x64, windows-aarch64, linux-x64, linux-aarch64, osx-x64, osx-aarch64
```
To install both backends and clients, you will need to run two commands.
**Backends**
```shell
mkdir ~/backends
./jetbrains-clients-downloader-linux-x86_64-1867/bin/jetbrains-clients-downloader --products-filter <product-code> --build-filter <build-number> --platforms-filter linux-x64,windows-x64,osx-x64 --download-backends ~/backends
```
**Clients**
This is the same command as above, with the `--download-backends` flag removed.
```shell
mkdir ~/clients
./jetbrains-clients-downloader-linux-x86_64-1867/bin/jetbrains-clients-downloader --products-filter <product-code> --build-filter <build-number> --platforms-filter linux-x64,windows-x64,osx-x64 ~/clients
```
We now have both clients and backends installed.
### 3. Install a web server
You will need to run a web server in order to serve requests to the backend and
client files. We installed `nginx` and setup an FQDN and routed all requests to
`/`. See below:
```console
server {
listen 80 default_server;
listen [::]:80 default_server;
root /var/www/html;
index index.html index.htm index.nginx-debian.html;
server_name _;
location / {
root /home/ubuntu;
}
}
```
Then, configure your DNS entry to point to the IP address of the server. For the
purposes of the POC, we did not configure TLS, although that is a supported
option.
### 4. Add Client Files
You will need to add the following files on your local machine in order for
Gateway to pull the backend and client from the server.
```shell
$ cat productsInfoUrl # a path to products.json that was generated by the backend's downloader (it could be http://, https://, or file://)
https://internal.site/backends/<PRODUCT_CODE>/products.json
$ cat clientDownloadUrl # a path for clients that you got from the clients' downloader (it could be http://, https://, or file://)
https://internal.site/clients/
$ cat jreDownloadUrl # a path for JBR that you got from the clients' downloader (it could be http://, https://, or file://)
https://internal.site/jre/
$ cat pgpPublicKeyUrl # a URL to the KEYS file that was downloaded with the clients builds.
https://internal.site/KEYS
```
The location of these files will depend upon your local operating system:
**macOS**
```console
# User-specific settings
/Users/UserName/Library/Application Support/JetBrains/RemoteDev
# System-wide settings
/Library/Application Support/JetBrains/RemoteDev/
```
**Linux**
```console
# User-specific settings
$HOME/.config/JetBrains/RemoteDev
# System-wide settings
/etc/xdg/JetBrains/RemoteDev/
```
**Windows**
```console
# User-specific settings
HKEY_CURRENT_USER registry
# System-wide settings
HKEY_LOCAL_MACHINE registry
```
Additionally, create a string for each setting with its appropriate value in
`SOFTWARE\JetBrains\RemoteDev`:
![Alt text](../../images/gateway/jetbrains-offline-windows.png)
### 5. Setup SSH connection with JetBrains Gateway
With the server now configured, you can now configure your local machine to use
Gateway. Here is the documentation to
[setup SSH config via the Coder CLI](../../user-guides/workspace-access/index.md#configure-ssh).
On the Gateway side, follow our guide here until step 16.
Instead of downloading from jetbrains.com, we will point Gateway to our server
endpoint. Select `Installation options...` and select `Use download link`. Note
that the URL must explicitly reference the archive file:
![Offline Gateway](../../images/gateway/offline-gateway.png)
Click `Download IDE and Connect`. Gateway should now download the backend and
clients from the server into your remote workspace and local machine,
respectively.
## JetBrains Fleet
JetBrains Fleet is a code editor and lightweight IDE designed to support various
programming languages and development environments.
[See JetBrains' website to learn about Fleet](https://www.jetbrains.com/fleet/)
Fleet can connect to a Coder workspace by following these steps.
1. [Install Fleet](https://www.jetbrains.com/fleet/download)
2. Install Coder CLI
```shell
curl -L https://coder.com/install.sh | sh
```
3. Login and configure Coder SSH.
```shell
coder login coder.example.com
coder config-ssh
```
4. Connect via SSH with the Host set to `coder.workspace-name`
![Fleet Connect to Coder](../../images/fleet/ssh-connect-to-coder.png)
> If you experience problems, please
> [create a GitHub issue](https://github.com/coder/coder/issues) or share in
> [our Discord channel](https://discord.gg/coder).
docs/user-guides/workspace-access/port-forwarding.md
+161
View File
@@ -0,0 +1,161 @@
# Workspace Ports
## 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.
There are three ways to forward ports in Coder:
- The `coder port-forward` command
- Dashboard
- SSH
The `coder port-forward` command is generally more performant than:
1. The Dashboard which proxies traffic through the Coder control plane versus
peer-to-peer which is possible with the Coder CLI
1. `sshd` which does double encryption of traffic with both Wireguard and SSH
## 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.
The supported syntax variations for the `--tcp` and `--udp` flag are:
- Single port with optional remote port: `local_port[:remote_port]`
- Comma separation `local_port1,local_port2`
- Port ranges `start_port-end_port`
- Any combination of the above
### Examples
Forward the remote TCP port `8080` to local port `8000`:
```console
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.
```console
coder port-forward myworkspace --tcp 3000,9990-9999
```
For more examples, see `coder port-forward --help`.
## Dashboard
> To enable port forwarding via the dashboard, Coder must be configured with a
> [wildcard access URL](../../admin/setup/index.md#wildcard-access-url). If an
> access URL is not specified, Coder will create
> [a publicly accessible URL](../../admin/setup/index.md#tunnel) to reverse
> proxy the deployment, and port forwarding will work.
>
> There is a
> [DNS limitation](https://datatracker.ietf.org/doc/html/rfc1035#section-2.3.1)
> where each segment of hostnames must not exceed 63 characters. If your app
> name, agent name, workspace name and username exceed 63 characters in the
> hostname, port forwarding via the dashboard will not work.
### From an coder_app resource
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:
```tf
# node app
resource "coder_app" "node-react-app" {
agent_id = coder_agent.dev.id
slug = "node-react-app"
icon = "https://upload.wikimedia.org/wikipedia/commons/a/a7/React-icon.svg"
url = "http://localhost:3000"
subdomain = true
share = "authenticated"
healthcheck {
url = "http://localhost:3000/healthz"
interval = 10
threshold = 30
}
}
```
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/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
You can share ports as URLs, either with other authenticated coder users or
publicly. Using the open ports interface, you 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 visibility regardless of whether or not
it is still accessible.
![Annotated port controls in the UI](../../images/networking/annotatedports.png)
> The sharing level is limited by the maximum level enforced in the template
> settings in enterprise deployments, and not restricted in OSS deployments.
This can also be used to change the sharing level of port-based `coder_app`s by
entering their port number in the sharable ports UI. The `share` attribute on
`coder_app` resource uses a different method of authentication and **is not
impacted by the template's maximum sharing level**, nor the level of a shared
port that points to the app.
### 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 also 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/
```
## SSH
First, [configure SSH](./index.md#configure-ssh) 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).
docs/user-guides/workspace-access/remote-desktops.md
+60
View File
@@ -0,0 +1,60 @@
# Remote Desktops
> Built-in remote desktop is on the roadmap
> ([#2106](https://github.com/coder/coder/issues/2106)).
## VNC Desktop
The common way to use remote desktops with Coder is through VNC.
![VNC Desktop in Coder](../../images/vnc-desktop.png)
Workspace requirements:
- VNC server (e.g. [tigervnc](https://tigervnc.org/))
- VNC client (e.g. [novnc](https://novnc.com/info.html))
Installation instructions vary depending on your workspace's operating system,
platform, and build system.
As a starting point, see the
[desktop-container](https://github.com/bpmct/coder-templates/tree/main/desktop-container)
community template. It builds and provisions a Dockerized workspace with the
following software:
- Ubuntu 20.04
- TigerVNC server
- noVNC client
- XFCE Desktop
## RDP Desktop
To use RDP with Coder, you'll need to install an
[RDP client](https://docs.microsoft.com/en-us/windows-server/remote/remote-desktop-services/clients/remote-desktop-clients)
on your local machine, and enable RDP on your workspace.
Use the following command to forward the RDP port to your local machine:
```console
coder port-forward <workspace-name> --tcp 3399:3389
```
Then, connect to your workspace via RDP:
```console
mstsc /v localhost:3399
```
or use your favorite RDP client to connect to `localhost:3399`.
![windows-rdp](../../images/ides/windows_rdp_client.png)
> Note: Default username is `Administrator` and password is `coderRDP!`.
## RDP Web
Our [WebRDP](https://registry.coder.com/modules/windows-rdp) module in the Coder
Registry adds a one-click button to open an RDP session in the browser. This
requires just a few lines of Terraform in your template, see the documentation
on our registry for setup.
![Web RDP Module in a Workspace](../../images/user-guides/web-rdp-demo.png)
docs/user-guides/workspace-access/vscode.md
+159
View File
@@ -0,0 +1,159 @@
# Visual Studio Code
You can develop in your Coder workspace remotely with
[VSCode](https://code.visualstudio.com/download). We support connecting with the
desktop client and VSCode in the browser with [code-server](#code-server).
## VSCode Desktop
VSCode desktop is a default app for workspaces.
Click `VS Code Desktop` in the dashboard to one-click enter a workspace. This
automatically installs the [Coder Remote](https://github.com/coder/vscode-coder)
extension, authenticates with Coder, and connects to the workspace.
![Demo](https://github.com/coder/vscode-coder/raw/main/demo.gif?raw=true)
> The `VS Code Desktop` button can be hidden by enabling
> [Browser-only connections](../../admin/networking/index.md#browser-only-connections-enterprise).
### Manual Installation
You can install our extension manually in VSCode using the command palette.
Launch VS Code Quick Open (Ctrl+P), paste the following command, and press
enter.
```text
ext install coder.coder-remote
```
Alternatively, manually install the VSIX from the
[latest release](https://github.com/coder/vscode-coder/releases/latest).
## VS Code extensions
There are multiple ways to add extensions to VS Code Desktop:
1. Using the
[public extensions marketplaces](#using-the-public-extensions-marketplaces)
with Code Web (code-server)
1. Adding [extensions to custom images](#adding-extensions-to-custom-images)
1. Installing extensions
[using its `vsix` file at the command line](#installing-extensions-using-its-vsix-file-at-the-command-line)
1. Installing extensions
[from a marketplace using the command line](#installing-from-a-marketplace-at-the-command-line)
### Using the public extensions marketplaces
You can manually add an extension while you're working in the Code Web IDE. The
extensions can be from Coder's public marketplace, Eclipse Open VSX's public
marketplace, or the Eclipse Open VSX _local_ marketplace.
![Code Web Extensions](../../images/ides/code-web-extensions.png)
> Note: Microsoft does not allow any unofficial VS Code IDE to connect to the
> extension marketplace.
### Adding extensions to custom images
You can add extensions to a custom image and install them either through Code
Web or using the workspace's terminal.
1. Download the extension(s) from the Microsoft public marketplace.
![Code Web Extensions](../../images/ides/copilot.png)
1. Add the `vsix` extension files to the same folder as your Dockerfile.
```shell
~/images/base
➜ ls -l
-rw-r--r-- 1 coder coder 0 Aug 1 19:23 Dockerfile
-rw-r--r-- 1 coder coder 8925314 Aug 1 19:40 GitHub.copilot.vsix
```
1. In the Dockerfile, add instructions to make a folder and to copy the `vsix`
files into the newly created folder.
```Dockerfile
FROM codercom/enterprise-base:ubuntu
# Run below commands as root user
USER root
# Download and install VS Code extensions into the container
RUN mkdir -p /vsix
ADD ./GitHub.copilot.vsix /vsix
USER coder
```
1. Build the custom image, and push it to your image registry.
1. Pass in the image and below command into your template `startup_script` (be
sure to update the filename below):
**Startup Script**
```tf
resource "coder_agent" "main" {
...
startup_script = "code-server --install-extension /vsix/Github.copilot.vsix"
}
```
**Image Definition**
```tf
resource "kubernetes_deployment" "main" {
spec {
template {
spec {
container {
name = "dev"
image = "registry.internal/image-name:tag"
}
}
}
}
}
```
1. Create a workspace using the template.
You will now have access to the extension in your workspace.
### Installing extensions using its `vsix` file at the command line
Using the workspace's terminal or the terminal available inside `code-server`,
you can install an extension whose files you've downloaded from a marketplace:
```console
/path/to/code-server --install-extension /vsix/Github.copilot.vsix
```
### Installing from a marketplace at the command line
Using the workspace's terminal or the terminal available inside Code Web (code
server), run the following to install an extension (be sure to update the
snippets with the name of the extension you want to install):
```console
SERVICE_URL=https://extensions.coder.com/api ITEM_URL=https://extensions.coder.com/item /path/to/code-server --install-extension GitHub.copilot
```
Alternatively, you can install an extension from Open VSX's public marketplace:
```console
SERVICE_URL=https://open-vsx.org/vscode/gallery ITEM_URL=https://open-vsx.org/vscode/item /path/to/code-server --install-extension GitHub.copilot
```
### Using VS Code Desktop
For your local VS Code to pickup extension files in your Coder workspace,
include this command in your `startup_script`, or run in manually in your
workspace terminal:
```console
code --extensions-dir ~/.vscode-server/extensions --install-extension "$extension"
```
docs/user-guides/workspace-access/web-ides.md
+81
View File
@@ -0,0 +1,81 @@
# Web IDEs
By default, Coder workspaces allow connections via:
- Web terminal
- [SSH](./index.md#ssh)
It's common to also connect via web IDEs for uses cases like zero trust
networks, data science, contractors, and infrequent code contributors.
![Row of IDEs](../../images/ide-row.png)
In Coder, web IDEs are defined as
[coder_app](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/app)
resources in the template. With our generic model, any web application can be
used as a Coder application. For example:
> To learn more about configuring IDEs in templates, see our docs on
> [template administration](../../admin/templates/index.md).
![External URLs](../../images/external-apps.png)
## code-server
[`code-server`](https://github.com/coder/code-server) is our supported method of
running VS Code in the web browser. You can read more in our
[documentation for code-server](https://coder.com/docs/code-server).
![code-server in a workspace](../../images/code-server-ide.png)
## VS Code Web
We also support Microsoft's official product for using VS Code in the browser. A
template administrator can add it by following the
[Extending Templates](../../admin/templates/extending-templates/web-ides.md#vs-code-web)
guide.
![VS Code Web in Coder](../../images/vscode-web.gif)
## Jupyter Notebook
Jupyter Notebook is a web-based interactive computing platform. A template
administrator can add it by following the
[Extending Templates](../../admin/templates/extending-templates/web-ides.md#jupyter-notebook)
guide.
![Jupyter Notebook in Coder](../../images/jupyter-notebook.png)
## JupyterLab
In addition to Jupyter Notebook, you can use Jupyter lab in your workspace. A
template administrator can add it by following the
[Extending Templates](../../admin/templates/extending-templates/web-ides.md#jupyterlab)
guide.
![JupyterLab in Coder](../../images/jupyter.png)
## RStudio
RStudio is a popular IDE for R programming language. A template administrator
can add it to your workspace by following the
[Extending Templates](../../admin/templates/extending-templates/web-ides.md#rstudio)
guide.
![RStudio in Coder](../../images/rstudio-port-forward.png)
## Airflow
Apache Airflow is an open-source workflow management platform for data
engineering pipelines. A template administrator can add it by following the
[Extending Templates](../../admin/templates/extending-templates/web-ides.md#airflow)
guide.
![Airflow in Coder](../../images/airflow-port-forward.png)
## SSH Fallback
If you prefer to run web IDEs in localhost, you can port forward using
[SSH](../index.md#ssh) or the Coder CLI `port-forward` sub-command. Some web
IDEs may not support URL base path adjustment so port forwarding is the only
approach.