coder · bpmct · Jun 19, 2022 · Jun 17, 2022 · Jun 17, 2022 · Jun 19, 2022
diff --git a/docs/ides.md b/docs/ides.md
@@ -16,6 +16,8 @@ support should work:
   - Rider
   - RubyMine
   - WebStorm
+- Web IDEs (code-server, JupyterLab, Jetbrains Projector)
+   - Note: These are [configured in the template](./ides/configuring-web-ides.md)
 
 ## SSH configuration
 
@@ -57,88 +59,6 @@ Code, connected to your Coder workspace for compute, etc.
 1. In VS Code's left-hand nav bar, click **Remote Explorer** and right-click on
    a workspace to connect.
 
-## VS Code in the browser
+## Web IDEs (Jupyter, code-server, Jetbrains Projector)
 
-> You must have Docker Desktop running for this template to work.
-
-Coder offers a [sample template that includes
-code-server](../examples/templates/docker-code-server/README.md).
-
-To use:
-
-1. Start Coder:
-
-  ```console
-  coder server --dev
-  ```
-
-1. Open a new terminal and run:
-
-  ```console
-  coder templates init
-  ```
-
-1. Select the **Develop code-server in Docker** option when prompted.
-
-1. Navigate into your new folder and create your sample template:
-
-  ```console
-  cd code-server-docker && coder templates create
-  ```
-
-  Follow the prompts that appear in the terminal.
-
-1. Create your workspace:
-
-  ```console
-  coder create --template="docker-code-server" [workspace name]
-  ```
-
-1. Log into Coder's Web UI, and open your workspace. Then,
-   click **code-server** to launch VS Code in a new browser window.
-
-## JetBrains Gateway with SSH
-
-If your image
-[includes a JetBrains IDE](../admin/workspace-management/installing-jetbrains.md)
-and you've [set up SSH access to Coder](./ssh.md), you can use JetBrains Gateway
-to run a local JetBrains IDE connected to your Coder workspace.
-
-> See the [Docker sample template](../examples/templates/docker/main.tf) for an
-> example of how to refer to images in your template.
-
-Please note that:
-
-- Your Coder workspace must be running, and Gateway needs compute resources, so
-  monitor your resource usage on the Coder dashboard and adjust accordingly.
-- If you use a premium JetBrains IDE (e.g., GoLand, IntelliJ IDEA Ultimate), you
-  will still need a license to use it remotely with Coder.
-
-1. [Download and install JetBrains Toolbox](https://www.jetbrains.com/toolbox-app/).
-   Locate JetBrains Gateway in the Toolbox list and click **Install**.
-
-1. Open JetBrains Gateway and click **Connect via SSH** within the **Run the IDE
-   Remotely** section.
-
-1. Click the small **gear icon** to the right of the **Connection** field, then
-   the **+** button on the next screen to create a new configuration.
-
-1. Enter your Coder workspace alias target in **Host** (e.g.,
-   `coder.<yourWorkspaceName>`), `22` in **Port**, `coder` in **User name**, and change
-   **Authentication Type** to **OpenSSH config and authentication agent**. Leave
-   the local port field blank. Click **Test Connection**. If the test is
-   successful, click **Ok** at the bottom to proceed.
-
-1. With your created configuration in the **Connection** chosen in the drop-down
-   field, click **Check Connection and Continue**.
-
-1. Select a JetBrains IDE from the **IDE version** drop-down (make sure that you
-   choose the IDE included in your image), then click the folder icon and select the
-   `/home/coder` directory in your Coder workspace. Click **Download and Start
-   IDE** to proceed.
-
-1. During this installation step, Gateway downloads the IDE and a JetBrains
-   client. This may take a couple of minutes.
-
-1. When your IDE download is complete, JetBrains will prompt you for your
-   license. When done, you'll be able to use your IDE.
+Web IDEs (code-server, JetBrains Projector, VNC, etc.) are defined in the template. See [configuring IDEs](./templates/configuring-ides.md).
diff --git a/docs/ides/configuring-web-ides.md b/docs/ides/configuring-web-ides.md
@@ -0,0 +1,146 @@
+# Configuring web IDEs
+
+By default, Coder workspaces allow connections via:
+
+- Web terminal
+- SSH (plus any [SSH-compatible IDE](../ides.md))
+
+It's common to also let developers to connect via web IDEs.
+
+![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. This gives you full control over the version,
+behavior, and configuration for applications in your workspace.
+
+## code-server
+
+![code-server in a workspace](../images/code-server-ide.png)
+
+[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:
+
+```sh
+# edit your template
+cd your-template/ 
+vim main.tf
+```
+
+```hcl
+resource "coder_agent" "dev" {
+    arch          = "amd64"
+    os            = "linux"
+    startup_script = <<EOF
+    #!/bin/sh
+    # install and start code-server
+    curl -fsSL https://code-server.dev/install.sh | sh
+    code-server --auth none --port 13337
+    EOF
+}
+```
+
+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/):
+
+```Dockerfile
+FROM codercom/enterprise-base:ubuntu
+
+# install a specific code-server version
+RUN curl -fsSL https://code-server.dev/install.sh | sh -s -- --version=4.3.0
+
+# pre-install versions
+RUN code-server --install-extension eamodio.gitlens 
+
+# directly start code-server with the agent's startup_script (see above),
+# or use a proccess manager like supervisord
+```
+
+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.
+
+```hcl
+resource "coder_app" "code-server" {
+  agent_id = coder_agent.dev.id
+  name     = "VS Code"
+  url      = "http://localhost:13337/?folder=/home/coder"
+  icon     = "/code.svg"
+}
+```
+
+## VNC Desktop
+
+![VNC Desktop in Coder](../images/vnc-desktop.png)
+
+You may want a full desktop environment to develop with/preview specialized software. 
+
+Workspace requirements:
+
+- VNC server (e.g. [tigervnc](https://tigervnc.org/))
+- VNC client (e.g. [novnc](https://novnc.com/info.html))
+
+Installation instructions will vary depending on your workspace's operating system, platform, and build system.
+
+> Coder-provided VNC clients are on the roadmap ([#2106](https://github.com/coder/coder/issues/2106)).
+
+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:
+
+- Ubuntu 20.04
+- TigerVNC server
+- noVNC client
+- XFCE Desktop 
+
+## JetBrains Projector
+
+[JetBrains Projector](https://jetbrains.github.io/projector-client/mkdocs/latest/) is a JetBrains Incubator project which renders JetBrains IDEs in the web browser.
+
+![JetBrains Projector in Coder](../images/jetbrains-projector.png)
+
+> 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!)
+
+Workspace requirements:
+
+- JetBrains server
+- IDE (e.g IntelliJ IDEA, pyCharm)
+
+Installation instructions will vary depending on your workspace's operating system, platform, and build system.
+
+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:
+
+- CLion
+- pyCharm
+- DataGrip
+- IntelliJ IDEA Community
+- IntelliJ IDEA Ultimate
+- PhpStorm
+- pyCharm Community
+- PyCharm Professional
+- Rider
+- Rubymine
+- WebStorm
+- ➕ code-server (just in case!)
+
+## Custom IDEs and applications
+
+As long as the process is running on the specified port inside your resource, you support any application.
+
+```sh
+# edit your template
+cd your-template/ 
+vim main.tf
+```
+
+```hcl
+resource "coder_app" "portainer" {
+  agent_id      = coder_agent.dev.id
+  name          = "portainer"
+  icon          = "https://simpleicons.org/icons/portainer.svg"
+  url           = "http://localhost:8000"
+  relative_path = true
+}
+```
+
+> The full `coder_app` schema is described in the 
+> [Terraform provider](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/app).
+
+```sh
+# update your template
+coder templates update your-template
+```
diff --git a/docs/images/code-server-ide.png b/docs/images/code-server-ide.png
diff --git a/docs/images/custom-app.png b/docs/images/custom-app.png
diff --git a/docs/images/ide-row.png b/docs/images/ide-row.png
diff --git a/docs/images/jetbrains-projector.png b/docs/images/jetbrains-projector.png
diff --git a/docs/images/vnc-desktop.png b/docs/images/vnc-desktop.png
diff --git a/docs/manifest.json b/docs/manifest.json
@@ -1,5 +1,7 @@
 {
-  "versions": ["0.6.6"],
+  "versions": [
+    "0.6.6"
+  ],
   "routes": [
     {
       "title": "About",
@@ -32,13 +34,12 @@
       "path": "./templates.md",
       "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>",
       "children": [
-            {
-              "title": "Authentication & Secrets",
-              "description": "Learn how to authenticate the provisioner",
-              "path": "./templates/authentication.md",
-              "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>"
-            }
-          ]
+        {
+          "title": "Authentication & Secrets",
+          "description": "Learn how to authenticate the provisioner",
+          "path": "./templates/authentication.md"
+        }
+      ]
     },
     {
       "title": "Workspaces",
@@ -49,8 +50,15 @@
     {
       "title": "IDEs",
       "description": "Learn how to use your IDE of choice with Coder.",
+      "path": "./ides.md",
       "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>",
-      "path": "./ides.md"
+      "children": [
+        {
+          "title": "Configuring Web IDEs",
+          "description": "Learn how to configure web IDEs in your templates",
+          "path": "./ides/configuring-web-ides.md"
+        }
+      ]
     },
     {
       "title": "Dotfiles",