coder · bpmct · Jun 19, 2022 · Jun 17, 2022 · Jun 17, 2022 · Jun 19, 2022
diff --git a/docs/ides.md b/docs/ides.md
@@ -17,6 +17,9 @@ support should work:
   - RubyMine
   - WebStorm
 
+> See [Congifuring IDEs](./templates/configuring-ides.md) to learn how to 
+> add any web IDE (e.g. code-server, JetBrains projector) to your templates.
+
 ## SSH configuration
 
 > Before proceeding, run `coder login <accessURL>` if you haven't already to
@@ -142,3 +145,7 @@ Please note that:
 
 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
+
+Web IDEs (code-server, JetBrains Projector, VNC, etc.) are defined in the template. See [configuring IDEs](./templates/configuring-ides.md).
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,17 @@
       "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": "Configuring Web IDEs",
+          "description": "Learn how to configure web IDEs in your templates",
+          "path": "./templates/configuring-web-ides.md"
+        },
+        {
+          "title": "Authentication & Secrets",
+          "description": "Learn how to authenticate the provisioner",
+          "path": "./templates/authentication.md"
+        }
+      ]
     },
     {
       "title": "Workspaces",

diff --git a/docs/templates/configuring-web-ides.md b/docs/templates/configuring-web-ides.md
@@ -0,0 +1,149 @@
+# 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
+}
+```
+
+> Alternatively, you can build your own VM/container images that install and run code-server.
+
+Optionally customize code-server:
+
+```sh
+# Refer to the code-server docs for more options:
+# https://coder.com/docs/code-server
+
+# install a specific version
+curl -fsSL https://code-server.dev/install.sh | sh -s -- --version=4.3.0
+
+# pre-install extensions
+code-server --install-extension eamodio.gitlens 
+
+# start with custom flags (code-server --help)
+code-server --auth none --port 13337 --ignore-last-opened
+```
+
+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
+  nane     = "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
+```