docs: add Docker quickstart (coder#2875)

ammario · web-flow · commit 13d7466ebca3 · 2022-07-11T12:05:05.000-05:00
* Fix docker-compose file

* Add docker quickstart
diff --git a/docker-compose.yaml b/docker-compose.yaml
@@ -1,7 +1,9 @@
 version: "3.9"
 services:
   coder:
-    image: ghcr.io/coder/coder:v${CODER_VERSION:-latest}
+    # This MUST be stable for our documentation and
+    # other automations.
+    image: ghcr.io/coder/coder:${CODER_VERSION:-latest}
     ports:
       - "7080:7080"
     environment:
diff --git a/docs/ides/configuring-web-ides.md b/docs/ides/configuring-web-ides.md
@@ -70,9 +70,9 @@ You'll also need to specify a `coder_app` resource related to the agent. This is
 ```hcl
 resource "coder_app" "code-server" {
   agent_id = coder_agent.dev.id
-  name     = "VS Code"
+  name     = "code-server"
   url      = "http://localhost:13337/?folder=/home/coder"
-  icon     = "/code.svg"
+  icon     = "/icon/code.svg"
 }
 ```
 
diff --git a/docs/images/quickstart/docker/create-workspace.png b/docs/images/quickstart/docker/create-workspace.png
diff --git a/docs/images/quickstart/docker/ides.png b/docs/images/quickstart/docker/ides.png
diff --git a/docs/images/quickstart/docker/login.png b/docs/images/quickstart/docker/login.png
diff --git a/docs/install.md b/docs/install.md
@@ -55,13 +55,16 @@ Coder](https://github.com/coder/coder/releases) installed.
    git clone https://github.com/coder/coder.git
    ```
 
-2. Navigate into the `coder` folder. Coder requires a non-`localhost` access URL
-   for non-Docker-based examples; if you have a public IP or a domain/reverse
-   proxy, you can provide this value before running `docker-compose up` to
-   start the service:
+2. Navigate into the `coder` folder and run `docker-compose up`:
 
    ```console
    cd coder
+   # Coder will bind to localhost:7080.
+   # You may use localhost:7080 as your access URL
+   # when using Docker workspaces exclusively.
+   #  CODER_ACCESS_URL=http://localhost:7080
+   # Otherwise, an internet accessible access URL
+   # is required.
    CODER_ACCESS_URL=https://coder.mydomain.com
    docker-compose up
    ```
diff --git a/docs/manifest.json b/docs/manifest.json
@@ -39,7 +39,21 @@
       "title": "Quickstart",
       "description": "Create your first template and workspace",
       "icon": "<svg class=\"MuiSvgIcon-root MuiSvgIcon-fontSizeMedium MuiBox-root css-uqopch\" focusable=\"false\" aria-hidden=\"true\" viewBox=\"0 0 24 24\"><path d=\"M12 17.27 18.18 21l-1.64-7.03L22 9.24l-7.19-.61L12 2 9.19 8.63 2 9.24l5.46 4.73L5.82 21z\"></path></svg>",
-      "path": "./quickstart.md"
+      "path": "./quickstart.md",
+      "children": [
+        {
+          "title": "Docker",
+          "description": "Setup Coder with Docker",
+          "icon": "<?xml version=\"1.0\" ?><svg viewBox=\"0 0 640 512\" xmlns=\"http:\/\/www.w3.org\/2000\/svg\"><path d=\"M349.9 236.3h-66.1v-59.4h66.1v59.4zm0-204.3h-66.1v60.7h66.1V32zm78.2 144.8H362v59.4h66.1v-59.4zm-156.3-72.1h-66.1v60.1h66.1v-60.1zm78.1 0h-66.1v60.1h66.1v-60.1zm276.8 100c-14.4-9.7-47.6-13.2-73.1-8.4-3.3-24-16.7-44.9-41.1-63.7l-14-9.3-9.3 14c-18.4 27.8-23.4 73.6-3.7 103.8-8.7 4.7-25.8 11.1-48.4 10.7H2.4c-8.7 50.8 5.8 116.8 44 162.1 37.1 43.9 92.7 66.2 165.4 66.2 157.4 0 273.9-72.5 328.4-204.2 21.4.4 67.6.1 91.3-45.2 1.5-2.5 6.6-13.2 8.5-17.1l-13.3-8.9zm-511.1-27.9h-66v59.4h66.1v-59.4zm78.1 0h-66.1v59.4h66.1v-59.4zm78.1 0h-66.1v59.4h66.1v-59.4zm-78.1-72.1h-66.1v60.1h66.1v-60.1z\"\/><\/svg>",
+          "path": "./quickstart/docker.md"
+        },
+        {
+          "title": "Generic",
+          "description": "Setup Coder on anything",
+          "icon": "<svg viewBox=\"0 0 32 32\" xmlns=\"http:\/\/www.w3.org\/2000\/svg\"><ellipse cx=\"16\" cy=\"16\" rx=\"4\" ry=\"3.11\" transform=\"rotate(-30 15.991 16.005)\" fill=\"#ffffff\" class=\"fill-00bbff\"><\/ellipse><ellipse cx=\"16\" cy=\"16\" rx=\"4\" ry=\"3.11\" transform=\"rotate(-30 15.991 16.005)\" fill=\"none\" stroke=\"#ffffff\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2px\" class=\"stroke-000000\"><\/ellipse><path d=\"M29 8.5c1.93 3.35-.18 8.19-4.73 10.82s-9.8 2-11.73-1.32\" fill=\"none\" stroke=\"#ffffff\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2px\" class=\"stroke-000000\"><\/path><path d=\"M17.49 3.06c4.69-.48 8.08 2.78 7.56 7.28a8.47 8.47 0 0 1-.18 1M4.46 11c2.76-3.83 8.27-5.51 12.31-3.76s5.07 6.27 2.31 10.1\" fill=\"none\" stroke=\"#ffffff\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2px\" class=\"stroke-000000\"><\/path><path d=\"M3 23.5c-1.93-3.35.18-8.19 4.73-10.82q.43-.25.86-.45M14.56 28.53C9.86 29 6.47 25.84 7 21.46s4.72-8.32 9.41-8.8\" fill=\"none\" stroke=\"#ffffff\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2px\" class=\"stroke-000000\"><\/path><path d=\"M27.54 21c-2.76 3.83-8.27 5.51-12.31 3.76a7.44 7.44 0 0 1-.72-.36\" fill=\"none\" stroke=\"#ffffff\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2px\" class=\"stroke-000000\"><\/path><\/svg>",
+          "path": "./quickstart/generic.md"
+        }
+      ]
     },
     {
       "title": "Templates",
diff --git a/docs/quickstart.md b/docs/quickstart.md
@@ -1,51 +1,6 @@
 # Quickstart
 
-## Prerequisites
+See our [Docker quickstart](./quickstart/docker.md) for the easiest
+possible way to use Coder.
 
-Please [install Coder](./install.md) before proceeding with the steps outlined in this article.
-
-## Creating your first template and workspace
-
-In a new terminal window, run the following to copy a sample template:
-
-```bash
-coder templates init
-```
-
-Follow the CLI instructions to select an example that you can modify for your
-specific usage (e.g., a template to **Develop code-server in Docker**):
-
-1. Navigate into your new templates folder and create your first template using
-   the provided command (e.g., `cd ./docker-code-server && coder templates create`)
-
-1. Answer the CLI prompts; when done, confirm that you want to create your template.
-
-Create a workspace using your template:
-
-```bash
-coder create --template="yourTemplate" <workspaceName>
-```
-
-Connect to your workspace via SSH:
-
-```bash
-coder ssh <workspaceName>
-```
-
-You can also access your workspace using the **access URL** you provided when
-deploying Coder (if you're using a temporary deployment and you opted to use
-Coder's tunnel, use the access URL you were provided). Log in with the admin
-credentials provided to you by Coder.
-
-![Coder Web UI with code-server](images/code-server.png)
-
-## Modifying templates
-
-You can edit the Terraform template as follows:
-
-```sh
-coder templates init
-cd gcp-linux # modify this line as needed to access the template
-vim main.tf
-coder templates update gcp-linux # updates the template
-```
+Otherwise, you can check out the [generic quickstart](./quickstart/generic.md).
diff --git a/docs/quickstart/docker.md b/docs/quickstart/docker.md
@@ -0,0 +1,83 @@
+# Docker
+
+Coder with Docker has the following advantages:
+
+- Simple installation (everything is on a single box)
+- Workspace images are easily configured
+- Workspaces share resources for burst operations
+
+## Requirements
+
+- A single MacOS or Linux box
+- A running Docker daemon
+
+## Instructions
+
+1.  [Install and launch Coder](../install.md)
+
+    You may use `CODER_ACCESS_URL=http://localhost:7080` since we're using local
+    Docker workspaces exclusively. The rest of the guide will assume that this is your
+    access URL.
+
+    ```bash
+    coder server -a $CODER_ACCESS_URL
+    ```
+
+1.  Run `coder login http://localhost:7080` in a new terminal and follow the
+    interactive instructions to create your user.
+
+1.  Pull the example template:
+
+    ```bash
+    echo "docker" | coder templates init
+    cd docker
+    # You should see a `main.tf` file in this directory
+    ```
+
+1.  Open up `main.tf` in your preferred editor to edit the images
+
+    You can skip this step if you're fine with our default, generic OS images.
+
+    Search for the following section in `main.tf`:
+
+    ```hcl
+    ...
+    variable "docker_image" {
+     description = "Which Docker image would you like to use for your workspace?"
+     # The codercom/enterprise-* images are only built for amd64
+     default = "codercom/enterprise-base:ubuntu"
+     validation {
+         condition     = contains(["codercom/enterprise-base:ubuntu", "codercom/enterprise-node:ubuntu",
+                                 "codercom/enterprise-intellij:ubuntu", "codercom/enterprise-golang:ubuntu"], var.docker_image)
+         error_message = "Invalid Docker image!"
+     }
+    }
+    ...
+    ```
+
+    And edit the strings in `condition = contains([...])` and `default = ...`
+    with your preferred images.
+
+1.  Push up the template to Coder with `coder templates create`
+1.  Open the dashboard in your browser (http://localhost:7080) to create your
+    first workspace:
+
+    <img src="./images/quickstart/docker/login.png">
+
+    Then navigate to `Templates > docker > Create workspace`
+
+    <img src="./images/quickstart/docker/create-workspace.png">
+
+    Now wait a few moments for the workspace to build... After the first build
+    the image is cached and subsequent builds will take a few seconds.
+
+1.  All done!
+
+    <img src="./images/quickstart/docker/ides.png">
+
+    Open up a web application or [SSH in](../ides.md#ssh-configuration).
+
+## Next Steps
+
+- [Learn more about template configuration](../templates.md)
+- [Configure more IDEs](../ides/configuring-web-ides.md)
diff --git a/docs/quickstart/generic.md b/docs/quickstart/generic.md
@@ -0,0 +1,49 @@
+## Prerequisites
+
+Please [install Coder](./install.md) before proceeding with the steps outlined in this article.
+
+## Creating your first template and workspace
+
+In a new terminal window, run the following to copy a sample template:
+
+```bash
+coder templates init
+```
+
+Follow the CLI instructions to select an example that you can modify for your
+specific usage (e.g., a template to **Develop code-server in Docker**):
+
+1. Navigate into your new templates folder and create your first template using
+   the provided command (e.g., `cd ./docker-code-server && coder templates create`)
+
+1. Answer the CLI prompts; when done, confirm that you want to create your template.
+
+Create a workspace using your template:
+
+```bash
+coder create --template="yourTemplate" <workspaceName>
+```
+
+Connect to your workspace via SSH:
+
+```bash
+coder ssh <workspaceName>
+```
+
+You can also access your workspace using the **access URL** you provided when
+deploying Coder (if you're using a temporary deployment and you opted to use
+Coder's tunnel, use the access URL you were provided). Log in with the admin
+credentials provided to you by Coder.
+
+![Coder Web UI with code-server](images/code-server.png)
+
+## Modifying templates
+
+You can edit the Terraform template as follows:
+
+```sh
+coder templates init
+cd gcp-linux # modify this line as needed to access the template
+vim main.tf
+coder templates update gcp-linux # updates the template
+```
diff --git a/examples/templates/docker/main.tf b/examples/templates/docker/main.tf
@@ -66,10 +66,24 @@ data "coder_workspace" "me" {
 }
 
 resource "coder_agent" "dev" {
-  arch = var.step2_arch
-  os   = "linux"
+  arch           = var.step2_arch
+  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
 }
 
+resource "coder_app" "code-server" {
+  agent_id = coder_agent.dev.id
+  name     = "code-server"
+  url      = "http://localhost:13337/?folder=/home/coder"
+  icon     = "/icon/code.svg"
+}
+
+
 variable "docker_image" {
   description = "Which Docker image would you like to use for your workspace?"
   # The codercom/enterprise-* images are only built for amd64
@@ -83,7 +97,7 @@ variable "docker_image" {
 }
 
 resource "docker_volume" "home_volume" {
-  name = "coder-${data.coder_workspace.me.owner}-${data.coder_workspace.me.name}-root"
+  name = "coder-${data.coder_workspace.me.owner}-${data.coder_workspace.me.name}-home"
 }
 
 resource "docker_container" "workspace" {
@@ -95,8 +109,14 @@ resource "docker_container" "workspace" {
   hostname = lower(data.coder_workspace.me.name)
   dns      = ["1.1.1.1"]
   # Use the docker gateway if the access URL is 127.0.0.1
-  command = ["sh", "-c", replace(coder_agent.dev.init_script, "127.0.0.1", "host.docker.internal")]
-  env     = ["CODER_AGENT_TOKEN=${coder_agent.dev.token}"]
+  command = [
+    "sh", "-c",
+    <<EOT
+    trap '[ $? -ne 0 ] && echo === Agent script exited with non-zero code. Sleeping infinitely to preserve logs... && sleep infinity' EXIT
+    ${replace(coder_agent.dev.init_script, "localhost", "host.docker.internal")}
+    EOT
+  ]
+  env = ["CODER_AGENT_TOKEN=${coder_agent.dev.token}"]
   host {
     host = "host.docker.internal"
     ip   = "host-gateway"
