Skip to content

Commit a19493b

Browse files
authored
add docs for web IDEs (code-server, JetBrains Projector, VNC) (#2448)
* add "configuring web IDEs" doc * no jupyterhub for now * change location of web IDE page * add Dockerfile example * add run instructions
1 parent 9bdaec6 commit a19493b

8 files changed

+167
-93
lines changed

docs/ides.md

+4-84
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,8 @@ support should work:
1616
- Rider
1717
- RubyMine
1818
- WebStorm
19+
- Web IDEs (code-server, JupyterLab, Jetbrains Projector)
20+
- Note: These are [configured in the template](./ides/configuring-web-ides.md)
1921

2022
## SSH configuration
2123

@@ -57,88 +59,6 @@ Code, connected to your Coder workspace for compute, etc.
5759
1. In VS Code's left-hand nav bar, click **Remote Explorer** and right-click on
5860
a workspace to connect.
5961

60-
## VS Code in the browser
62+
## Web IDEs (Jupyter, code-server, Jetbrains Projector)
6163

62-
> You must have Docker Desktop running for this template to work.
63-
64-
Coder offers a [sample template that includes
65-
code-server](../examples/templates/docker-code-server/README.md).
66-
67-
To use:
68-
69-
1. Start Coder:
70-
71-
```console
72-
coder server --dev
73-
```
74-
75-
1. Open a new terminal and run:
76-
77-
```console
78-
coder templates init
79-
```
80-
81-
1. Select the **Develop code-server in Docker** option when prompted.
82-
83-
1. Navigate into your new folder and create your sample template:
84-
85-
```console
86-
cd code-server-docker && coder templates create
87-
```
88-
89-
Follow the prompts that appear in the terminal.
90-
91-
1. Create your workspace:
92-
93-
```console
94-
coder create --template="docker-code-server" [workspace name]
95-
```
96-
97-
1. Log into Coder's Web UI, and open your workspace. Then,
98-
click **code-server** to launch VS Code in a new browser window.
99-
100-
## JetBrains Gateway with SSH
101-
102-
If your image
103-
[includes a JetBrains IDE](../admin/workspace-management/installing-jetbrains.md)
104-
and you've [set up SSH access to Coder](./ssh.md), you can use JetBrains Gateway
105-
to run a local JetBrains IDE connected to your Coder workspace.
106-
107-
> See the [Docker sample template](../examples/templates/docker/main.tf) for an
108-
> example of how to refer to images in your template.
109-
110-
Please note that:
111-
112-
- Your Coder workspace must be running, and Gateway needs compute resources, so
113-
monitor your resource usage on the Coder dashboard and adjust accordingly.
114-
- If you use a premium JetBrains IDE (e.g., GoLand, IntelliJ IDEA Ultimate), you
115-
will still need a license to use it remotely with Coder.
116-
117-
1. [Download and install JetBrains Toolbox](https://www.jetbrains.com/toolbox-app/).
118-
Locate JetBrains Gateway in the Toolbox list and click **Install**.
119-
120-
1. Open JetBrains Gateway and click **Connect via SSH** within the **Run the IDE
121-
Remotely** section.
122-
123-
1. Click the small **gear icon** to the right of the **Connection** field, then
124-
the **+** button on the next screen to create a new configuration.
125-
126-
1. Enter your Coder workspace alias target in **Host** (e.g.,
127-
`coder.<yourWorkspaceName>`), `22` in **Port**, `coder` in **User name**, and change
128-
**Authentication Type** to **OpenSSH config and authentication agent**. Leave
129-
the local port field blank. Click **Test Connection**. If the test is
130-
successful, click **Ok** at the bottom to proceed.
131-
132-
1. With your created configuration in the **Connection** chosen in the drop-down
133-
field, click **Check Connection and Continue**.
134-
135-
1. Select a JetBrains IDE from the **IDE version** drop-down (make sure that you
136-
choose the IDE included in your image), then click the folder icon and select the
137-
`/home/coder` directory in your Coder workspace. Click **Download and Start
138-
IDE** to proceed.
139-
140-
1. During this installation step, Gateway downloads the IDE and a JetBrains
141-
client. This may take a couple of minutes.
142-
143-
1. When your IDE download is complete, JetBrains will prompt you for your
144-
license. When done, you'll be able to use your IDE.
64+
Web IDEs (code-server, JetBrains Projector, VNC, etc.) are defined in the template. See [configuring IDEs](./templates/configuring-ides.md).

docs/ides/configuring-web-ides.md

+146
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
# Configuring web IDEs
2+
3+
By default, Coder workspaces allow connections via:
4+
5+
- Web terminal
6+
- SSH (plus any [SSH-compatible IDE](../ides.md))
7+
8+
It's common to also let developers to connect via web IDEs.
9+
10+
![Row of IDEs](../images/ide-row.png)
11+
12+
In Coder, web IDEs are defined as
13+
[coder_app](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/app)
14+
resources in the template. This gives you full control over the version,
15+
behavior, and configuration for applications in your workspace.
16+
17+
## code-server
18+
19+
![code-server in a workspace](../images/code-server-ide.png)
20+
21+
[code-server](https://github.com/coder/coder) is our supported method of running VS Code in the web browser. A simple way to install code-server in Linux/MacOS workspaces is via the Coder agent in your template:
22+
23+
```sh
24+
# edit your template
25+
cd your-template/
26+
vim main.tf
27+
```
28+
29+
```hcl
30+
resource "coder_agent" "dev" {
31+
arch = "amd64"
32+
os = "linux"
33+
startup_script = <<EOF
34+
#!/bin/sh
35+
# install and start code-server
36+
curl -fsSL https://code-server.dev/install.sh | sh
37+
code-server --auth none --port 13337
38+
EOF
39+
}
40+
```
41+
42+
For advanced use, we recommend installing code-server in your VM snapshot or container image. Here's a Dockerfile which leverages some special [code-server features](https://coder.com/docs/code-server/):
43+
44+
```Dockerfile
45+
FROM codercom/enterprise-base:ubuntu
46+
47+
# install a specific code-server version
48+
RUN curl -fsSL https://code-server.dev/install.sh | sh -s -- --version=4.3.0
49+
50+
# pre-install versions
51+
RUN code-server --install-extension eamodio.gitlens
52+
53+
# directly start code-server with the agent's startup_script (see above),
54+
# or use a proccess manager like supervisord
55+
```
56+
57+
You'll also need to specify a `coder_app` resource related to the agent. This is how code-server is displayed on the workspace page.
58+
59+
```hcl
60+
resource "coder_app" "code-server" {
61+
agent_id = coder_agent.dev.id
62+
name = "VS Code"
63+
url = "http://localhost:13337/?folder=/home/coder"
64+
icon = "/code.svg"
65+
}
66+
```
67+
68+
## VNC Desktop
69+
70+
![VNC Desktop in Coder](../images/vnc-desktop.png)
71+
72+
You may want a full desktop environment to develop with/preview specialized software.
73+
74+
Workspace requirements:
75+
76+
- VNC server (e.g. [tigervnc](https://tigervnc.org/))
77+
- VNC client (e.g. [novnc](https://novnc.com/info.html))
78+
79+
Installation instructions will vary depending on your workspace's operating system, platform, and build system.
80+
81+
> Coder-provided VNC clients are on the roadmap ([#2106](https://github.com/coder/coder/issues/2106)).
82+
83+
As a starting point, see the [desktop-container](https://github.com/bpmct/coder-templates/tree/main/desktop-container) community template. It builds & provisions a Dockerized workspace with the following software:
84+
85+
- Ubuntu 20.04
86+
- TigerVNC server
87+
- noVNC client
88+
- XFCE Desktop
89+
90+
## JetBrains Projector
91+
92+
[JetBrains Projector](https://jetbrains.github.io/projector-client/mkdocs/latest/) is a JetBrains Incubator project which renders JetBrains IDEs in the web browser.
93+
94+
![JetBrains Projector in Coder](../images/jetbrains-projector.png)
95+
96+
> It is common to see latency and performance issues with Projector. We recommend using [Jetbrains Gateway](https://youtrack.jetbrains.com/issues/GTW) whenever possible (also no Template edits required!)
97+
98+
Workspace requirements:
99+
100+
- JetBrains server
101+
- IDE (e.g IntelliJ IDEA, pyCharm)
102+
103+
Installation instructions will vary depending on your workspace's operating system, platform, and build system.
104+
105+
As a starting point, see the [jetbrains-container](https://github.com/bpmct/coder-templates/tree/main/jetbrains-container) community template. It builds & provisions a Dockerized workspaces for the following IDEs:
106+
107+
- CLion
108+
- pyCharm
109+
- DataGrip
110+
- IntelliJ IDEA Community
111+
- IntelliJ IDEA Ultimate
112+
- PhpStorm
113+
- pyCharm Community
114+
- PyCharm Professional
115+
- Rider
116+
- Rubymine
117+
- WebStorm
118+
- ➕ code-server (just in case!)
119+
120+
## Custom IDEs and applications
121+
122+
As long as the process is running on the specified port inside your resource, you support any application.
123+
124+
```sh
125+
# edit your template
126+
cd your-template/
127+
vim main.tf
128+
```
129+
130+
```hcl
131+
resource "coder_app" "portainer" {
132+
agent_id = coder_agent.dev.id
133+
name = "portainer"
134+
icon = "https://simpleicons.org/icons/portainer.svg"
135+
url = "http://localhost:8000"
136+
relative_path = true
137+
}
138+
```
139+
140+
> The full `coder_app` schema is described in the
141+
> [Terraform provider](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/app).
142+
143+
```sh
144+
# update your template
145+
coder templates update your-template
146+
```

docs/images/code-server-ide.png

357 KB
Loading

docs/images/custom-app.png

620 KB
Loading

docs/images/ide-row.png

15.8 KB
Loading

docs/images/jetbrains-projector.png

771 KB
Loading

docs/images/vnc-desktop.png

3.77 MB
Loading

docs/manifest.json

+17-9
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
{
2-
"versions": ["0.6.6"],
2+
"versions": [
3+
"0.6.6"
4+
],
35
"routes": [
46
{
57
"title": "About",
@@ -40,13 +42,12 @@
4042
"path": "./templates.md",
4143
"icon": "<svg viewBox=\"0 0 16 16\" xmlns=\"http://www.w3.org/2000/svg\"> <path d=\"M15.0017 4.0017H1.0017C0.868289 3.99368 0.734692 4.01405 0.609732 4.06147C0.484772 4.10889 0.371292 4.18228 0.276784 4.27678C0.182276 4.37129 0.108891 4.48477 0.0614728 4.60973C0.0140548 4.73469 -0.00631686 4.86829 0.00170278 5.0017V15.0017C-0.00631686 15.1351 0.0140548 15.2687 0.0614728 15.3937C0.108891 15.5186 0.182276 15.6321 0.276784 15.7266C0.371292 15.8211 0.484772 15.8945 0.609732 15.9419C0.734692 15.9894 0.868289 16.0097 1.0017 16.0017H15.0017C15.1351 16.0097 15.2687 15.9894 15.3937 15.9419C15.5186 15.8945 15.6321 15.8211 15.7266 15.7266C15.8211 15.6321 15.8945 15.5186 15.9419 15.3937C15.9894 15.2687 16.0097 15.1351 16.0017 15.0017V5.0017C16.0097 4.86829 15.9894 4.73469 15.9419 4.60973C15.8945 4.48477 15.8211 4.37129 15.7266 4.27678C15.6321 4.18228 15.5186 4.10889 15.3937 4.06147C15.2687 4.01405 15.1351 3.99368 15.0017 4.0017ZM14.0017 14.0017H2.0017V6.0017H14.0017V14.0017Z\" /> <path d=\"M14 0H2V2H14V0Z\" fill=\"#333333\"/> <path d=\"M5 13L10 8L13 13H5Z\" /> <path d=\"M5 10C5.55228 10 6 9.55228 6 9C6 8.44772 5.55228 8 5 8C4.44772 8 4 8.44772 4 9C4 9.55228 4.44772 10 5 10Z\" /> </svg>",
4244
"children": [
43-
{
44-
"title": "Authentication & Secrets",
45-
"description": "Learn how to authenticate the provisioner",
46-
"path": "./templates/authentication.md",
47-
"icon": "<svg xmlns=\"http://www.w3.org/2000/svg\" height=\"24\" viewBox=\"0 0 24 24\" width=\"24\"><path d=\"M0 0h24v24H0z\" fill=\"none\"/><path d=\"M18 8h-1V6c0-2.76-2.24-5-5-5S7 3.24 7 6v2H6c-1.1 0-2 .9-2 2v10c0 1.1.9 2 2 2h12c1.1 0 2-.9 2-2V10c0-1.1-.9-2-2-2zm-6 9c-1.1 0-2-.9-2-2s.9-2 2-2 2 .9 2 2-.9 2-2 2zm3.1-9H8.9V6c0-1.71 1.39-3.1 3.1-3.1 1.71 0 3.1 1.39 3.1 3.1v2z\"/></svg>"
48-
}
49-
]
45+
{
46+
"title": "Authentication & Secrets",
47+
"description": "Learn how to authenticate the provisioner",
48+
"path": "./templates/authentication.md"
49+
}
50+
]
5051
},
5152
{
5253
"title": "Workspaces",
@@ -57,8 +58,15 @@
5758
{
5859
"title": "IDEs",
5960
"description": "Learn how to use your IDE of choice with Coder.",
61+
"path": "./ides.md",
6062
"icon": "<svg viewBox=\"0 0 512 466\" xmlns=\"http://www.w3.org/2000/svg\">\n<path d=\"M46.5 0.837754C20.5 0.837754 0 22.3052 0 49.5321V122.94V196.348V221.062V245.776V270.489V343.898V417.306C0 444.533 20.5 466 46.5 466H256H465.5C491.5 466 512 444.533 512 417.306V343.898V244.205V195.511V122.102V48.6944C512 21.4674 491.5 0 465.5 0H256H46.5V0.837754Z\" />\n<path d=\"M70.1 73.1V99.1L140.2 140.1L70.1 181.1V207.1L186.7 140.1L70.1 73.1ZM185.9 186.5V210.1H302.5V186.5H185.9Z\" fill=\"white\" />\n</svg>",
61-
"path": "./ides.md"
63+
"children": [
64+
{
65+
"title": "Configuring Web IDEs",
66+
"description": "Learn how to configure web IDEs in your templates",
67+
"path": "./ides/configuring-web-ides.md"
68+
}
69+
]
6270
},
6371
{
6472
"title": "Dotfiles",

0 commit comments

Comments
 (0)