mirror of
https://github.com/coder/coder.git
synced 2026-09-24 15:04:27 +08:00
docs: restructure docs (#14421)
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
co-authored by
Ethan
Ethan Dickson
Ben Potter
Stephen Kirby
Stephen Kirby
EdwardAngert
Edward Angert
Ethan
Ethan Dickson
Ben Potter
Stephen Kirby
Stephen Kirby
EdwardAngert
Edward Angert
parent
288df75686
commit
419eba5fb6
@@ -0,0 +1,10 @@
|
||||
# User Guides
|
||||
|
||||
These guides contain information on workspace management, workspace access via
|
||||
IDEs, environment personalization, and workspace scheduling.
|
||||
|
||||
These are intended for end-user flows only. If you are an administrator, please
|
||||
refer to our docs on configuring [templates](../admin/index.md) or the
|
||||
[control plane](../admin/index.md).
|
||||
|
||||
<children></children>
|
||||
@@ -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.
|
||||
@@ -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. 
|
||||
@@ -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.
|
||||
|
||||
|
||||
|
||||
## Terminal
|
||||
|
||||
The terminal is implicitly enabled in Coder and allows you to access your
|
||||
workspace through the shell environment set by your template.
|
||||
|
||||
|
||||
|
||||
## 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).
|
||||
|
||||
|
||||
|
||||
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).
|
||||
|
||||
|
||||
|
||||
## 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).
|
||||
|
||||
|
||||
|
||||
## Remote Desktops
|
||||
|
||||
Coder also supports connecting with an RDP solution, see our
|
||||
[RDP guide](./remote-desktops.md) for details.
|
||||
@@ -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:
|
||||
|
||||
|
||||
|
||||
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**:
|
||||
|
||||
|
||||
|
||||
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**:
|
||||
|
||||
|
||||
|
||||
1. Select the JetBrains IDE for your project and the project directory then
|
||||
click **Start IDE and connect**:
|
||||
|
||||
|
||||
|
||||
Gateway connects using the IDE you selected:
|
||||
|
||||
|
||||
|
||||
> 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**:
|
||||
|
||||
|
||||
|
||||
### 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**:
|
||||
|
||||
|
||||
|
||||
1. In the resulting dialog, click the gear icon to the right of **Connection**:
|
||||
|
||||
|
||||
|
||||
1. Click <kbd>+</kbd> to add a new SSH connection:
|
||||
|
||||
|
||||
|
||||
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**:
|
||||
|
||||
|
||||
|
||||
1. Select the connection you just added:
|
||||
|
||||
|
||||
|
||||
1. Click **Check Connection and Continue**:
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
> Note the JetBrains IDE is remotely installed into
|
||||
> `~/. cache/JetBrains/RemoteDev/dist`
|
||||
|
||||
1. Click **Download and Start IDE** to connect.
|
||||
|
||||
|
||||
|
||||
## 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`:
|
||||
|
||||
|
||||
|
||||
### 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:
|
||||
|
||||
|
||||
|
||||
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`
|
||||
|
||||
|
||||
> 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).
|
||||
@@ -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.
|
||||
|
||||
|
||||
|
||||
## 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).
|
||||
|
||||
|
||||
|
||||
### 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.
|
||||
|
||||
|
||||
|
||||
> 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).
|
||||
@@ -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.
|
||||
|
||||
|
||||
|
||||
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`.
|
||||
|
||||
|
||||
> 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.
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
|
||||
> 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.
|
||||
|
||||
|
||||
|
||||
> 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.
|
||||
|
||||
|
||||
|
||||
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"
|
||||
```
|
||||
@@ -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.
|
||||
|
||||
|
||||
|
||||
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).
|
||||
|
||||
|
||||
|
||||
## 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).
|
||||
|
||||
|
||||
|
||||
## 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.
|
||||
|
||||
|
||||
|
||||
## 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.
|
||||
|
||||
|
||||
|
||||
## 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.
|
||||
|
||||
|
||||
|
||||
## 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.
|
||||
|
||||
|
||||
|
||||
## 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.
|
||||
|
||||
|
||||
|
||||
## 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.
|
||||
@@ -0,0 +1,71 @@
|
||||
# Dotfiles
|
||||
|
||||
<!-- markdown-link-check-disable -->
|
||||
|
||||
Coder offers the `coder dotfiles <repo>` command which simplifies workspace
|
||||
personalization. Our behavior is consistent with Codespaces, so
|
||||
[their documentation](https://docs.github.com/en/codespaces/customizing-your-codespace/personalizing-codespaces-for-your-account#dotfiles)
|
||||
explains how it loads your repo.
|
||||
|
||||
<!-- markdown-link-check-enable -->
|
||||
|
||||
You can read more on dotfiles best practices [here](https://dotfiles.github.io).
|
||||
|
||||
## From templates
|
||||
|
||||
Templates can prompt users for their dotfiles repo URL, which will personalize
|
||||
your workspace automatically.
|
||||
|
||||
|
||||
|
||||
> Template admins: this can be enabled quite easily with a our
|
||||
> [dotfiles module](https://registry.coder.com/modules/dotfiles) using just a
|
||||
> few lines in the template.
|
||||
|
||||
## Personalize script
|
||||
|
||||
Templates may be configured to support executing a `~/personalize` script on
|
||||
startup which users can populate with commands to customize their workspaces.
|
||||
|
||||
You can even fill `personalize` with `coder dotfiles <repo>`, but those looking
|
||||
for a simpler approach can inline commands like so:
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
sudo apt update
|
||||
# Install some of my favorite tools every time my workspace boots
|
||||
sudo apt install -y neovim fish cargo
|
||||
```
|
||||
|
||||
> Template admins: refer to
|
||||
> [this module](https://registry.coder.com/modules/personalize) to enable the
|
||||
> `~/personalize` script on templates.
|
||||
|
||||
## Setup script support
|
||||
|
||||
User can setup their dotfiles by creating one of the following script files in
|
||||
their dotfiles repo:
|
||||
|
||||
- `install.sh`
|
||||
- `install`
|
||||
- `bootstrap.sh`
|
||||
- `bootstrap`
|
||||
- `script/bootstrap`
|
||||
- `setup.sh`
|
||||
- `setup`
|
||||
- `script/setup`
|
||||
|
||||
If any of the above files are found (in the specified order), Coder will try to
|
||||
execute the first match. After the first match is found, other files will be
|
||||
ignored.
|
||||
|
||||
The setup script must be executable, otherwise the dotfiles setup will fail. If
|
||||
you encounter this issue, you can fix it by making the script executable using
|
||||
the following commands:
|
||||
|
||||
```shell
|
||||
cd <path_to_dotfiles_repo>
|
||||
chmod +x <script_name>
|
||||
git commit -m "Make <script_name> executable" <script_name>
|
||||
git push
|
||||
```
|
||||
@@ -0,0 +1,116 @@
|
||||
# Workspace lifecycle
|
||||
|
||||
Workspaces are flexible, reproducible, and isolated units of compute. Workspaces
|
||||
are created via Terraform, managed through the Coder control plane, accessed
|
||||
through the Coder agent, then stopped and deleted again by Terraform.
|
||||
|
||||
This page covers how workspaces move through this lifecycle. To learn about
|
||||
automating workspace schedules for cost control, read the
|
||||
[workspace scheduling docs](./workspace-scheduling.md).
|
||||
|
||||
## Workspace ephemerality
|
||||
|
||||
Workspaces are composed of resources which may be _ephemeral_ or _persistent_.
|
||||
Persistent resources stay provisioned when the workspace is stopped, where as
|
||||
ephemeral resources are destroyed and recreated on restart. All resources are
|
||||
destroyed when a workspace is deleted.
|
||||
|
||||
> Template administrators can learn more about resource configuration in the
|
||||
> [extending templates docs](../admin/templates/extending-templates/resource-persistence.md).
|
||||
|
||||
## Workspace States
|
||||
|
||||
Generally, there are 3 states that a workspace may fall into:
|
||||
|
||||
- Running: Started and ready for connections
|
||||
- Stopped: Ephemeral resources destroyed, persistent resources idle
|
||||
- Deleted: All resources destroyed, workspace records removed from database
|
||||
|
||||
If some error occurs during the above, a workspace may fall into one of the
|
||||
following broken states:
|
||||
|
||||
- Failed: Failure during provisioning, no resource consumption
|
||||
- Unhealthy: Resources have been provisioned, but the agent can't facilitate
|
||||
connections
|
||||
|
||||
## Workspace creation
|
||||
|
||||
Workspaces are created from [templates](../admin/templates/index.md) via the
|
||||
CLI, API, or dashboard.
|
||||
|
||||
By default, there is no limit on the number of workspaces a user may create,
|
||||
regardless of the template's resource demands. Enterprise administrators may
|
||||
limit the number of workspaces per template, group, and organization using
|
||||
[quotas](../admin/users/quotas.md) to prevent over provisioning and control
|
||||
costs.
|
||||
|
||||
When a user creates a workspace, they're sending a build request to the control
|
||||
plane. Coder takes this and uses [Terraform](https://www.terraform.io/) to
|
||||
provision a workspace defined by your [template](../admin/templates/index.md).
|
||||
Generally, templates define the resources and environment of a workspace.
|
||||
|
||||
The resources that run the agent are described as _computational resources_,
|
||||
while those that don't are called _peripheral resources_. A workspace must
|
||||
contain some computational resource to run the Coder agent process.
|
||||
|
||||
The provisioned workspace's computational resources start the agent process,
|
||||
which opens connections to your workspace via SSH, the terminal, and IDES such
|
||||
as [JetBrains](./workspace-access/jetbrains.md) or
|
||||
[VSCode](./workspace-access/vscode.md).
|
||||
|
||||
Once started, the Coder agent is responsible for running your workspace startup
|
||||
scripts. These may configure tools, service connections, or personalization with
|
||||
[dotfiles](./workspace-dotfiles.md).
|
||||
|
||||
Once these steps have completed, your workspace will now be in the `Running`
|
||||
state. You can access it via any of the [supported methods](./index.md), stop it
|
||||
when you're away, or delete it once it's no longer in use.
|
||||
|
||||
## Stopping workspaces
|
||||
|
||||
Workspaces may be stopped manually by users and admins in the dashboard, CLI, or
|
||||
API. Workspaces may be automatically stopped due to template updates or
|
||||
inactivity by [scheduling configuration](./workspace-scheduling.md).
|
||||
|
||||
Once stopped, a workspace may resume running by starting it manually, or via
|
||||
user connection if automatic start is enabled.
|
||||
|
||||
## Deleting workspaces
|
||||
|
||||
Similarly to stopping, workspaces may be deleted manually or automatically by
|
||||
Coder through workspace dormancy.
|
||||
|
||||
A delete workspace build runs `terraform destroy`, destroying both persistent
|
||||
and ephemeral resources. This action can not be reverted.
|
||||
|
||||
When enabled on enterprise deployments, workspaces will become dormant after a
|
||||
specified duration of inactivity. Then, if left dormant, the workspaces will be
|
||||
queued for deletion. Learn about configuring workspace dormancy in the template
|
||||
scheduling docs.
|
||||
|
||||
### Orphan resources
|
||||
|
||||
Typically, when a workspace is deleted, all of the workspace's resources are
|
||||
deleted along with it. Rarely, one may wish to delete a workspace without
|
||||
deleting its resources, e.g. a workspace in a broken state. Users with the
|
||||
Template Admin role have the option to do so both in the UI, and also in the CLI
|
||||
by running the delete command with the `--orphan` flag. This option should be
|
||||
considered cautiously as orphaning may lead to unaccounted cloud resources.
|
||||
|
||||
## Broken workspace states
|
||||
|
||||
During a workspace start or stop build, one of two errors may lead to a broken
|
||||
state. If the call to `terraform apply` fails to correctly provision resources,
|
||||
a workspace build has **failed**. If the computational resources fail to connect
|
||||
the agent, a workspace becomes **unhealthy**.
|
||||
|
||||
A failed workspace is most often caused by misalignment from the definition in
|
||||
your template's Terraform file and the target resources on your infrastructure.
|
||||
Unhealthy workspaces are usually caused by a misconfiguration in the agent or
|
||||
workspace startup scripts.
|
||||
|
||||
### Next steps
|
||||
|
||||
- [Connecting to your workspace](./index.md)
|
||||
- [Creating templates](../admin/templates/index.md)
|
||||
- [Workspace scheduling](./workspace-scheduling.md)
|
||||
@@ -0,0 +1,177 @@
|
||||
# Workspaces
|
||||
|
||||
A workspace is the environment that a developer works in. Developers in a team
|
||||
each work from their own workspace and can use
|
||||
[multiple IDEs](./workspace-access/index.md).
|
||||
|
||||
A developer creates a workspace from a
|
||||
[shared template](../admin/templates/index.md). This lets an entire team work in
|
||||
environments that are identically configured and provisioned with the same
|
||||
resources.
|
||||
|
||||
## Creating workspaces
|
||||
|
||||
You can create a workspace in the UI. Log in to your Coder instance, go to the
|
||||
**Templates** tab, find the template you need, and select **Create Workspace**.
|
||||
|
||||
|
||||
|
||||
When you create a workspace, you will be prompted to give it a name. You might
|
||||
also be prompted to set some parameters that the template provides.
|
||||
|
||||
You can manage your existing templates in the **Workspaces** tab.
|
||||
|
||||
You can also create a workspace from the command line:
|
||||
|
||||
Each Coder user has their own workspaces created from
|
||||
[templates](../admin/templates/index.md):
|
||||
|
||||
```shell
|
||||
# create a workspace from the template; specify any variables
|
||||
coder create --template="<templateName>" <workspaceName>
|
||||
|
||||
# show the resources behind the workspace and how to connect
|
||||
coder show <workspace-name>
|
||||
```
|
||||
|
||||
## Workspace filtering
|
||||
|
||||
In the Coder UI, you can filter your workspaces using pre-defined filters or
|
||||
Coder's filter query. Filters follow the pattern `[filter name]:[filter text]`
|
||||
and multiple filters can be specified separated by a space i.e
|
||||
`owner:me status:running`
|
||||
|
||||
The following filters are supported:
|
||||
|
||||
- `owner` - Represents the `username` of the owner. You can also use `me` as a
|
||||
convenient alias for the logged-in user, e.g., `owner:me`
|
||||
- `name` - Name of the workspace.
|
||||
- `template` - Name of the template.
|
||||
- `status` - Indicates the status of the workspace, e.g, `status:failed` For a
|
||||
list of supported statuses, see
|
||||
[WorkspaceStatus documentation](https://pkg.go.dev/github.com/coder/coder/codersdk#WorkspaceStatus).
|
||||
- `outdated` - Filters workspaces using an outdated template version, e.g,
|
||||
`outdated:true`
|
||||
- `dormant` - Filters workspaces based on the dormant state, e.g `dormant:true`
|
||||
- `has-agent` - Only applicable for workspaces in "start" transition. Stopped
|
||||
and deleted workspaces don't have agents. List of supported values
|
||||
`connecting|connected|timeout`, e.g, `has-agent:connecting`
|
||||
- `id` - Workspace UUID
|
||||
|
||||
## Updating workspaces
|
||||
|
||||
After updating the default version of the template that a workspace was created
|
||||
from, you can update the workspace.
|
||||
|
||||
|
||||
|
||||
If the workspace is running, Coder stops it, updates it, then starts the
|
||||
workspace again.
|
||||
|
||||
### Updating via the CLI
|
||||
|
||||
Update a workspace through the command line:
|
||||
|
||||
```shell
|
||||
coder update <workspace-name>
|
||||
```
|
||||
|
||||
### Automatic updates
|
||||
|
||||
It can be tedious to manually update a workspace everytime an update is pushed
|
||||
to a template. Users can choose to opt-in to automatic updates to update to the
|
||||
active template version whenever the workspace is started.
|
||||
|
||||
Note: If a template is updated such that new parameter inputs are required from
|
||||
the user, autostart will be disabled for the workspace until the user has
|
||||
manually updated the workspace.
|
||||
|
||||
|
||||
|
||||
## Bulk operations (enterprise) (premium)
|
||||
|
||||
Enterprise admins may apply bulk operations (update, delete, start, stop) in the
|
||||
**Workspaces** tab. Select the workspaces you'd like to modify with the
|
||||
checkboxes on the left, then use the top-right **Actions** dropdown to apply the
|
||||
operation.
|
||||
|
||||
The start and stop operations can only be applied to a set of workspaces which
|
||||
are all in the same state. For update and delete, the user will be prompted for
|
||||
confirmation before any action is taken.
|
||||
|
||||
|
||||
|
||||
## Starting and stopping workspaces
|
||||
|
||||
By default, you manually start and stop workspaces as you need. You can also
|
||||
schedule a workspace to start and stop automatically.
|
||||
|
||||
To set a workspace's schedule, go to the workspace, then **Settings** >
|
||||
**Schedule**.
|
||||
|
||||
|
||||
|
||||
Coder might also stop a workspace automatically if there is a
|
||||
[template update](../admin/templates/index.md#Start/stop) available.
|
||||
|
||||
Learn more about [workspace lifecycle](./workspace-lifecycle.md) and our
|
||||
[scheduling features](./workspace-scheduling.md).
|
||||
|
||||
## Workspace resources
|
||||
|
||||
Workspaces in Coder are started and stopped, often based on whether there was
|
||||
any activity or if there was a [template update](../admin/templates/index.md)
|
||||
available.
|
||||
|
||||
Resources are often destroyed and re-created when a workspace is restarted,
|
||||
though the exact behavior depends on the template. For more information, see
|
||||
[Resource Persistence](../admin/templates/extending-templates/resource-persistence.md).
|
||||
|
||||
## Repairing workspaces
|
||||
|
||||
Use the following command to re-enter template input variables in an existing
|
||||
workspace. This command is useful when a workspace fails to build because its
|
||||
state is out of sync with the template.
|
||||
|
||||
```shell
|
||||
coder update <your workspace name> --always-prompt
|
||||
```
|
||||
|
||||
First, try re-entering parameters from a workspace. In the Coder UI, you can
|
||||
filter your workspaces using pre-defined filters or employing the Coder's filter
|
||||
query. Take a look at the following examples to understand how to use the
|
||||
Coder's filter query:
|
||||
|
||||
- To find the workspaces that you own, use the filter `owner:me`.
|
||||
- To find workspaces that are currently running, use the filter
|
||||
`status:running`.
|
||||
|
||||
|
||||
|
||||
You can also do this in the CLI with the following command:
|
||||
|
||||
```shell
|
||||
coder update <your workspace name> --always-prompt
|
||||
```
|
||||
|
||||
If that does not work, a Coder admin can manually push and pull the Terraform
|
||||
state for a given workspace. This can lead to state corruption or deleted
|
||||
resources if you do not know what you are doing.
|
||||
|
||||
```shell
|
||||
coder state pull <username>/<workspace name>
|
||||
# Make changes
|
||||
coder state push <username>/<workspace name>
|
||||
```
|
||||
|
||||
## Logging
|
||||
|
||||
Coder stores macOS and Linux logs at the following locations:
|
||||
|
||||
| Service | Location |
|
||||
| ----------------- | -------------------------------- |
|
||||
| `startup_script` | `/tmp/coder-startup-script.log` |
|
||||
| `shutdown_script` | `/tmp/coder-shutdown-script.log` |
|
||||
| Agent | `/tmp/coder-agent.log` |
|
||||
|
||||
> Note: Logs are truncated once they reach 5MB in size.
|
||||
@@ -0,0 +1,110 @@
|
||||
# Managing workspace schedules
|
||||
|
||||
Scheduling helps minimize cloud costs without sacrificing the availability of
|
||||
your workspaces.
|
||||
|
||||
You can configure each workspace to automatically start in the morning, and
|
||||
automatically stop once you log off. Coder also features an inactivity timeout,
|
||||
configured by your template admin, which will stop a workspace when a user's
|
||||
absence is detected.
|
||||
|
||||
To learn more workspace states and schedule, read the
|
||||
[workspace lifecycle](../user-guides/workspace-lifecycle.md) documentation.
|
||||
|
||||
## Where to find the schedule settings
|
||||
|
||||
Click on any workspace the **Workspaces** tab of the dashboard, then go to
|
||||
**Workspace settings** in the top right.
|
||||
|
||||
|
||||
|
||||
Then open the **Schedule** tab to see your workspace scheduling options.
|
||||
|
||||
|
||||
|
||||
## Autostart
|
||||
|
||||
> Autostart must be enabled in the template settings by your administrator.
|
||||
|
||||
Use autostart to start a workspace at a specified time and which days of the
|
||||
week. Also, you can choose your preferred timezone. Admins may restrict which
|
||||
days of the week your workspace is allowed to autostart.
|
||||
|
||||
|
||||
|
||||
## Autostop
|
||||
|
||||
Use autostop to stop a workspace after a number of hours. Autostop won't stop a
|
||||
workspace if you're still using it. It will wait for the user to become inactive
|
||||
before checking connections again (1 hour by default). Template admins can
|
||||
modify the inactivity timeout duration with the
|
||||
[inactivity bump](#inactivity-timeout) template setting. Coder checks for active
|
||||
connections in the IDE, SSH, Port Forwarding, and coder_app.
|
||||
|
||||
|
||||
|
||||
## Inactivity timeout
|
||||
|
||||
Workspaces will automatically shut down after a period of inactivity. This can
|
||||
be configured at the template level, but is visible in the autostop description
|
||||
for your workspace.
|
||||
|
||||
## Autostop requirement (enterprise) (premium)
|
||||
|
||||
Enterprise template admins may enforce a required stop for workspaces to apply
|
||||
updates or undergo maintenance. These stops ignore any active connections or
|
||||
inactivity bumps. Rather than being specified with a CRON, admins set a
|
||||
frequency for updates, either in **days** or **weeks**. Workspaces will apply
|
||||
the template autostop requirement on the given day **in the user's timezone**
|
||||
and specified quiet hours (see below).
|
||||
|
||||
> Admins: See the template schedule settings for more information on configuring
|
||||
> Autostop Requirement.
|
||||
|
||||
### User quiet hours (enterprise) (premium)
|
||||
|
||||
User quiet hours can be configured in the user's schedule settings page.
|
||||
Workspaces on templates with an autostop requirement will only be forcibly
|
||||
stopped due to the policy at the **start** of the user's quiet hours.
|
||||
|
||||
|
||||
|
||||
## Scheduling configuration examples
|
||||
|
||||
The combination of autostart, autostop, and the inactivity timer create a
|
||||
powerful system for scheduling your workspace. However, synchronizing all of
|
||||
them simultaneously can be somewhat challenging, here are a few example
|
||||
configurations to better understand how they interact.
|
||||
|
||||
> Note that the inactivity timer must be configured by your template admin.
|
||||
|
||||
### Working hours
|
||||
|
||||
The intended configuration for autostop is to combine it with autostart, and set
|
||||
a "working schedule" for your workspace. It's pretty intuitive:
|
||||
|
||||
If I want to use my workspace from 9 to 5 on weekdays, I would set my autostart
|
||||
to 9:00 AM every day with an autostop of 9 hours. My workspace will always be
|
||||
available during these hours, regardless of how long I spend away from my
|
||||
laptop. If I end up working overtime and log off at 6:00 PM, the inactivity
|
||||
timer will kick in, postponing the shutdown until 7:00 PM.
|
||||
|
||||
#### Basing solely on inactivity
|
||||
|
||||
If you'd like to ignore the TTL from autostop and have your workspace solely
|
||||
function on inactivity, you can **set your autostop equal to inactivity
|
||||
timeout**.
|
||||
|
||||
Let's say that both are set to 5 hours. When either your workspace autostarts or
|
||||
you sign in, you will have confidence that the only condition for shutdown is 5
|
||||
hours of inactivity.
|
||||
|
||||
## Dormancy (enterprise) (premium)
|
||||
|
||||
Dormancy automatically deletes workspaces which remain unused for long
|
||||
durations. Template admins configure an inactivity period after which your
|
||||
workspaces will gain a `dormant` badge. A separate period determines how long
|
||||
workspaces will remain in the dormant state before automatic deletion.
|
||||
|
||||
Enterprise admins may also configure failure cleanup, which will automatically
|
||||
delete workspaces that remain in a `failed` state for too long.
|
||||
Reference in New Issue
Block a user