Skip to content

Commit 08a781f

Browse files
sharkymarkammario
sharkymark
and
ammario
authored
docs: expand web IDE documentation
* docker group for coder user and code-server xterm issue and port-forward web IDEs * add screenshots of jupyterlab, rstudio and airflow in Coder * Clean up English in install and minor edits * Integrate Jupyter Co-authored-by: ammario <ammar@ammar.io>
1 parent dff6e97 commit 08a781f

File tree

5 files changed

+122
-32
lines changed

5 files changed

+122
-32
lines changed

‎docs/ides/configuring-web-ides.md

+95-23
Original file line numberDiff line numberDiff line change
@@ -11,8 +11,19 @@ It's common to also let developers to connect via web IDEs.
1111

1212
In Coder, web IDEs are defined as
1313
[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.
14+
resources in the template. With our generic model, any web application can
15+
be used as a Coder application. For example:
16+
17+
```hcl
18+
# Give template users the portainer.io web UI
19+
resource "coder_app" "portainer" {
20+
agent_id = coder_agent.dev.id
21+
name = "portainer"
22+
icon = "https://simpleicons.org/icons/portainer.svg"
23+
url = "http://localhost:8000"
24+
relative_path = true
25+
}
26+
```
1627

1728
## code-server
1829

@@ -22,7 +33,7 @@ behavior, and configuration for applications in your workspace.
2233

2334
```sh
2435
# edit your template
25-
cd your-template/
36+
cd your-template/
2637
vim main.tf
2738
```
2839

@@ -48,7 +59,7 @@ FROM codercom/enterprise-base:ubuntu
4859
RUN curl -fsSL https://code-server.dev/install.sh | sh -s -- --version=4.3.0
4960

5061
# pre-install versions
51-
RUN code-server --install-extension eamodio.gitlens
62+
RUN code-server --install-extension eamodio.gitlens
5263

5364
# directly start code-server with the agent's startup_script (see above),
5465
# or use a proccess manager like supervisord
@@ -65,11 +76,15 @@ resource "coder_app" "code-server" {
6576
}
6677
```
6778

79+
<blockquote class="warning">
80+
If the `code-server` integrated terminal fails to load, (i.e., xterm fails to load), go to DevTools to ensure xterm is loaded, clear your browser cache and refresh.
81+
</blockquote>
82+
6883
## VNC Desktop
6984

7085
![VNC Desktop in Coder](../images/vnc-desktop.png)
7186

72-
You may want a full desktop environment to develop with/preview specialized software.
87+
You may want a full desktop environment to develop with/preview specialized software.
7388

7489
Workspace requirements:
7590

@@ -85,7 +100,7 @@ As a starting point, see the [desktop-container](https://github.com/bpmct/coder-
85100
- Ubuntu 20.04
86101
- TigerVNC server
87102
- noVNC client
88-
- XFCE Desktop
103+
- XFCE Desktop
89104

90105
## JetBrains Projector
91106

@@ -117,30 +132,87 @@ As a starting point, see the [projector-container](https://github.com/bpmct/code
117132
- WebStorm
118133
- ➕ code-server (just in case!)
119134

120-
## Custom IDEs and applications
135+
## JupyterLab
121136

122-
As long as the process is running on the specified port inside your resource, you support any application.
137+
Configure your agent and `coder_app` like so to use Jupyter:
123138

124-
```sh
125-
# edit your template
126-
cd your-template/
127-
vim main.tf
139+
```hcl
140+
data "coder_workspace" "me" {}
141+
142+
## The name of the app must always be equal to the "/apps/<name>"
143+
## string in the base_url. This caveat is unique to Jupyter.
144+
145+
resource "coder_agent" "coder" {
146+
os = "linux"
147+
arch = "amd64"
148+
dir = "/home/coder"
149+
startup_script = <<-EOF
150+
pip3 install jupyterlab
151+
jupyter lab --ServerApp.base_url=/@${data.coder_workspace.me.owner}/${data.coder_workspace.me.name}/apps/jupyter/ --ServerApp.token='' --ip='*'
152+
EOF
153+
}
154+
155+
resource "coder_app" "jupyter" {
156+
agent_id = coder_agent.coder.id
157+
url = "http://localhost:8888/@${data.coder_workspace.me.owner}/${data.coder_workspace.me.name}/apps/jupyter"
158+
icon = "/icon/jupyter.svg"
159+
}
160+
```
161+
162+
![JupyterLab in Coder](../images/jupyterlab-port-forward.png)
163+
164+
## SSH Fallback
165+
166+
Certain Web IDEs don't support URL base path adjustment and thus can't be exposed with
167+
`coder_app`. In these cases you can use [SSH](../ides.md#ssh).
168+
169+
### RStudio
170+
171+
```hcl
172+
resource "coder_agent" "coder" {
173+
os = "linux"
174+
arch = "amd64"
175+
dir = "/home/coder"
176+
startup_script = <<EOT
177+
#!/bin/bash
178+
# start rstudio
179+
/usr/lib/rstudio-server/bin/rserver --server-daemonize=1 --auth-none=1 &
180+
EOT
181+
}
128182
```
129183

184+
From your local machine, start port forwarding and then open the IDE on
185+
http://localhost:8787.
186+
187+
```console
188+
ssh -L 8787:localhost:8787 coder.<RStudio workspace name>
189+
```
190+
191+
Check out this [RStudio Dockerfile](https://github.com/mark-theshark/dockerfiles/blob/main/rstudio/no-args/Dockerfile) for a starting point to creating a template.
192+
193+
![RStudio in Coder](../images/rstudio-port-forward.png)
194+
195+
### Airflow
196+
130197
```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
198+
resource "coder_agent" "coder" {
199+
os = "linux"
200+
arch = "amd64"
201+
dir = "/home/coder"
202+
startup_script = <<EOT
203+
#!/bin/bash
204+
# install and start airflow
205+
pip3 install apache-airflow 2>&1 | tee airflow-install.log
206+
/home/coder/.local/bin/airflow standalone 2>&1 | tee airflow-run.log &
207+
EOT
137208
}
138209
```
139210

140-
> The full `coder_app` schema is described in the
141-
> [Terraform provider](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/app).
211+
From your local machine, start port forwarding and then open the IDE on
212+
http://localhost:8080.
142213

143-
```sh
144-
# update your template
145-
coder templates update your-template
214+
```console
215+
ssh -L 8080:localhost:8080 coder.<Airflow workspace name>
146216
```
217+
218+
![Airflow in Coder](../images/airflow-port-forward.png)

‎docs/images/airflow-port-forward.png

276 KB
Loading

‎docs/images/jupyterlab-port-forward.png

367 KB
Loading

‎docs/images/rstudio-port-forward.png

365 KB
Loading

‎docs/install.md

+27-9
Original file line numberDiff line numberDiff line change
@@ -7,19 +7,19 @@ The easiest way to install Coder is to use our [install script](https://github.c
77
To install, run:
88

99
```bash
10-
curl -L https://coder.com/install.sh | sh
10+
curl -fsSL https://coder.com/install.sh | sh
1111
```
1212

1313
You can preview what occurs during the install process:
1414

1515
```bash
16-
curl -L https://coder.com/install.sh | sh -s -- --dry-run
16+
curl -fsSL https://coder.com/install.sh | sh -s -- --dry-run
1717
```
1818

1919
You can modify the installation process by including flags. Run the help command for reference:
2020

2121
```bash
22-
curl -L https://coder.com/install.sh | sh -s -- --help
22+
curl -fsSL https://coder.com/install.sh | sh -s -- --help
2323
```
2424

2525
## System packages
@@ -84,6 +84,24 @@ Coder](https://github.com/coder/coder/releases) installed.
8484

8585
3. Follow the on-screen instructions to create your first template and workspace
8686

87+
---
88+
89+
If the user is not in the Docker group, you will see the following error:
90+
91+
```sh
92+
Error: Error pinging Docker server: Got permission denied while trying to connect to the Docker daemon socket
93+
```
94+
95+
The default docker socket only permits connections from `root` or members of the `docker`
96+
group. Remedy like this:
97+
98+
```sh
99+
# replace "coder" with user running coderd
100+
sudo usermod -aG docker coder
101+
grep /etc/group -e "docker"
102+
sudo systemctl restart coder.service
103+
```
104+
87105
## Manual
88106
89107
We publish self-contained .zip and .tar.gz archives in [GitHub releases](https://github.com/coder/coder/releases). The archives bundle `coder` binary.
@@ -101,13 +119,13 @@ We publish self-contained .zip and .tar.gz archives in [GitHub releases](https:/
101119
102120
1. Start a Coder server
103121
104-
```sh
105-
# Automatically sets up an external access URL on *.try.coder.app
106-
coder server --tunnel
122+
```sh
123+
# Automatically sets up an external access URL on *.try.coder.app
124+
coder server --tunnel
107125
108-
# Requires a PostgreSQL instance and external access URL
109-
coder server --postgres-url <url> --access-url <url>
110-
```
126+
# Requires a PostgreSQL instance and external access URL
127+
coder server --postgres-url <url> --access-url <url>
128+
```
111129
112130
## Next steps
113131

0 commit comments

Comments
 (0)