docs: rename quickstart to platforms + Kubernetes guide (#6972)

* rename quickstart to platforms + Kubernetes guide * fmt
2026-09-24 15:04:27 +08:00 · 2023-04-03 09:51:07 -05:00
parent 2d051094e7
commit ded931f0f6
47 changed files with 103 additions and 65 deletions
@@ -121,5 +121,4 @@ respected in this case.

 ## Up Next

- [Get started using Coder](../quickstart.md).
 - [Learn how to upgrade Coder](./upgrade.md).
@@ -29,6 +29,5 @@ Coder publishes self-contained .zip and .tar.gz archives in [GitHub releases](ht

 ## Next steps

- [Quickstart](../quickstart.md)
 - [Configuring Coder](../admin/configure.md)
 - [Templates](../templates.md)
@@ -83,6 +83,5 @@ psql -U coder -c '\dn'

 ## Next steps

- [Quickstart](../quickstart.md)
 - [Configuring Coder](../admin/configure.md)
 - [Templates](../templates.md)
@@ -96,6 +96,5 @@ See Docker's official documentation to [Manage Docker as a non-root user](https:

 ## Next steps

- [Quickstart](../quickstart.md)
 - [Configuring Coder](../admin/configure.md)
 - [Templates](../templates.md)
@@ -168,6 +168,5 @@ See [troubleshooting templates](../templates.md#creating-and-troubleshooting-tem

 ## Next steps

- [Quickstart](../quickstart.md)
 - [Configuring Coder](../admin/configure.md)
 - [Templates](../templates.md)
@@ -37,6 +37,5 @@ sudo systemctl restart coder

 ## Next steps

- [Quickstart](../quickstart.md)
 - [Configuring Coder](../admin/configure.md)
 - [Templates](../templates.md)
@@ -30,6 +30,5 @@ Use the Windows installer to download the CLI and add Coder to `PATH`. Alternati

 ## Next steps

- [Quickstart](../quickstart.md)
 - [Configuring Coder](../admin/configure.md)
 - [Templates](../templates.md)
@@ -74,34 +74,44 @@
      ]
    },
    {
-      "title": "Quickstart",
-      "description": "Create your first template and workspace",
-      "path": "./quickstart.md",
+      "title": "Platforms",
+      "description": "Platform-specific guides using Coder",
+      "path": "./platforms.md",
      "icon_path": "./images/icons/star.svg",
      "children": [
        {
          "title": "Docker",
-          "description": "Setup Coder with Docker",
-          "path": "./quickstart/docker.md",
+          "description": "Set up Coder with Docker",
+          "path": "./platforms/docker.md",
          "icon_path": "./images/icons/docker.svg"
        },
-        {
-          "title": "Google Cloud Platform",
-          "description": "Setup Coder on a GCP Compute Engine VM",
-          "path": "./quickstart/google-cloud-platform.md",
-          "icon_path": "./images/google-cloud.svg"
-        },
        {
          "title": "AWS",
-          "description": "Setup Coder on an AWS EC2 VM",
-          "path": "./quickstart/aws.md",
+          "description": "Set up Coder on an AWS EC2 VM",
+          "path": "./platforms/aws.md",
          "icon_path": "./images/aws.svg"
        },
+        {
+          "title": "GCP",
+          "description": "Set up Coder on a GCP Compute Engine VM",
+          "path": "./platforms/google-cloud-platform.md",
+          "icon_path": "./images/google-cloud.svg"
+        },
        {
          "title": "Azure",
-          "description": "Setup Coder on an Azure VM",
-          "path": "./quickstart/azure.md",
+          "description": "Set up Coder on an Azure VM",
+          "path": "./platforms/azure.md",
          "icon_path": "./images/azure.svg"
+        },
+        {
+          "title": "Kubernetes",
+          "description": "Set up Coder on Kubernetes",
+          "path": "./platforms/kubernetes.md"
+        },
+        {
+          "title": "Other platforms",
+          "description": "Set up Coder on an another provider",
+          "path": "./platforms/other.md"
        }
      ]
    },
@@ -0,0 +1,7 @@
+# Platforms
+
+These platform-specific guides are the fastest way to try Coder. We'll walk you through installation and adding your first template and workspace.
+
+<children>
+  This page is rendered on https://coder.com/docs/coder-oss/latest/guides. Refer to the other documents in this directory for per-platform instructions.
+</children>
@@ -1,35 +1,35 @@
 # Amazon Web Services

-This quickstart is designed to get you up and running with a Coder proof-of-concept VM on AWS EC2 using a [Coder-provided AMI](https://github.com/coder/packages). If you are familiar with EC2 however, you can use our [install script](../install/install.sh.md) to run Coder on any popular Linux distribution.
+This guide is designed to get you up and running with a Coder proof-of-concept VM on AWS EC2 using a [Coder-provided AMI](https://github.com/coder/packages). If you are familiar with EC2 however, you can use our [install script](../install/install.sh.md) to run Coder on any popular Linux distribution.

 ## Requirements

-This quickstart assumes your AWS account has `AmazonEC2FullAccess` permissions.
+This guide assumes your AWS account has `AmazonEC2FullAccess` permissions.

 ## Launch a Coder instance from the from AWS Marketplace

 We publish an Ubuntu 22.04 AMI with Coder and Docker pre-installed. Search for `Coder` in the EC2 "Launch an Instance" screen or [launch directly from the marketplace](https://aws.amazon.com/marketplace/pp/prodview-5gxjyur2vc7rg).

-![Coder on AWS Marketplace](../images/quickstart/aws/marketplace.png)
+![Coder on AWS Marketplace](../images/platforms/aws/marketplace.png)

 Be sure to keep the default firewall (SecurityGroup) options checked so you can connect over HTTP, HTTPS, and SSH.

-![AWS Security Groups](../images/quickstart/aws/security-groups.png)
+![AWS Security Groups](../images/platforms/aws/security-groups.png)

-We recommend keeping the default instance type (`t2.xlarge`, 4 cores and 16 GB memory) if you plan on provisioning Docker containers as workspaces on this EC2 instance. Keep in mind this quickstart is intended for proof-of-concept deployments and you should adjust your infrastructure when preparing for production use. See: [Scaling Coder](../admin/scale.md)
+We recommend keeping the default instance type (`t2.xlarge`, 4 cores and 16 GB memory) if you plan on provisioning Docker containers as workspaces on this EC2 instance. Keep in mind this platforms is intended for proof-of-concept deployments and you should adjust your infrastructure when preparing for production use. See: [Scaling Coder](../admin/scale.md)

 Be sure to add a keypair so that you can connect over SSH to further [configure Coder](../admin/configure.md).

 After launching the instance, wait 30 seconds and navigate to the public IPv4 address. You should be redirected to a public tunnel URL.

 <video autoplay playsinline loop>
-  <source src="https://github.com/coder/coder/blob/main/docs/images/quickstart/aws/launch.mp4?raw=true" type="video/mp4">
+  <source src="https://github.com/coder/coder/blob/main/docs/images/platforms/aws/launch.mp4?raw=true" type="video/mp4">
 Your browser does not support the video tag.
 </video>

 That's all! Use the UI to create your first user, template, and workspace. We recommend starting with a Docker template since the instance has Docker pre-installed.

-![Coder Workspace and IDE in AWS EC2](../images/quickstart/aws/workspace.png)
+![Coder Workspace and IDE in AWS EC2](../images/platforms/aws/workspace.png)

 ## Configuring Coder server

@@ -47,13 +47,13 @@ Instead of running containers on the Coder instance, you can offer developers fu

 Before you add the AWS template from the dashboard or CLI, you'll need to modify the instance IAM role.

-![Modify IAM role](../images/quickstart/aws/modify-iam.png)
+![Modify IAM role](../images/platforms/aws/modify-iam.png)

 You must create or select a role that has `EC2FullAccess` permissions or a limited [Coder-specific permissions policy](https://github.com/coder/coder/tree/main/examples/templates/aws-linux#required-permissions--policy).

 From there, you can import the AWS starter template in the dashboard and begin creating VM-based workspaces.

-![Modify IAM role](../images/quickstart/aws/aws-linux.png)
+![Modify IAM role](../images/platforms/aws/aws-linux.png)

 ## Next steps

@@ -1,37 +1,37 @@
 # Microsoft Azure

-This quickstart shows you how to set up the Coder server on Azure which will
+This guide shows you how to set up the Coder server on Azure which will
 provision Azure-hosted Linux workspaces.

 ## Requirements

-This quickstart assumes you have full administrator privileges on Azure.
+This guide assumes you have full administrator privileges on Azure.

 ## Create An Azure VM

 From the Azure Portal, navigate to the Virtual Machines Dashboard. Click Create, and select creating a new Azure Virtual machine .

-<img src="../images/quickstart/azure/azure1.jpg">
+<img src="../images/platforms/azure/azure1.jpg">

 This will bring you to the `Create a virtual machine` page. Select the subscription group of your choice, or create one if necessary.

 Next, name the VM something relevant to this project using the naming convention of your choice. Change the region to something more appropriate for your current location. For this tutorial, we will use the base selection of the Ubuntu Gen2 Image and keep the rest of the base settings for this image the same.

-<img src="../images/quickstart/azure/azure2.png">
+<img src="../images/platforms/azure/azure2.png">

-<img src="../images/quickstart/azure/azure3.png">
+<img src="../images/platforms/azure/azure3.png">

 Up next, under `Inbound port rules` modify the Select `inbound ports` to also take in `HTTPS` and `HTTP`.

-<img src="../images/quickstart/azure/azure4.png">
+<img src="../images/platforms/azure/azure4.png">

 The set up for the image is complete at this stage. Click `Review and Create` - review the information and click `Create`. A popup will appear asking you to download the key pair for the server. Click `Download private key and create resource` and place it into a folder of your choice on your local system.

-<img src="../images/quickstart/azure/azure5.png">
+<img src="../images/platforms/azure/azure5.png">

 Click `Return to create a virtual machine`. Your VM will start up!

-<img src="../images/quickstart/azure/azure6.png">
+<img src="../images/platforms/azure/azure6.png">

 Click `Go to resource` in the virtual machine and copy the public IP address. You will need it to SSH into the virtual machine via your local machine.

@@ -77,11 +77,11 @@ You can now access Coder on your local machine with the relevant `***.try.coder.

 First, run `coder template init` to create your first template. You’ll be given a list of possible templates to use. This tutorial will show you how to set up your Coder instance to create a Linux based machine on Azure.

-<img src="../images/quickstart/azure/azure9.png">
+<img src="../images/platforms/azure/azure9.png">

 Press `enter` to select `Develop in Linux on Azure` template. This will return the following:

-<img src="../images/quickstart/azure/azure10.png">
+<img src="../images/platforms/azure/azure10.png">

 To get started using the Azure template, install the Azure CLI by following the instructions [here](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli-linux?pivots=apt). Run `az login` and follow the instructions to configure the Azure command line.

@@ -52,18 +52,18 @@ Coder with Docker has the following advantages:
 1. Open the dashboard in your browser to create your
   first workspace:

-   <img src="../images/quickstart/docker/login.png">
+   <img src="../images/platforms/docker/login.png">

   Then navigate to `Templates > docker > Create workspace`

-   <img src="../images/quickstart/docker/create-workspace.png">
+   <img src="../images/platforms/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. Your workspace is ready to go!

-   <img src="../images/quickstart/docker/ides.png">
+   <img src="../images/platforms/docker/ides.png">

   Open up a web application or [SSH in](../ides.md#ssh-configuration).

@@ -1,24 +1,24 @@
 # Google Cloud Platform

-In this quickstart, you will learn how to deploy the Coder control plane instance and your first template.
+In this guide, you will learn how to deploy the Coder control plane instance and your first template.

 ## Requirements

-This quickstart assumes you have `roles/compute.instanceAdmin.v1` access to your Google Cloud Platform project.
+This guide assumes you have `roles/compute.instanceAdmin.v1` access to your Google Cloud Platform project.

 ## Setting Up your VM

 If this is the first time you’re creating a VM on this project, you will need to enable the `Compute Engine API`. On the Compute Engine API page, click `enable` and wait for the service to finish connecting.

-<img src="../images/quickstart/google-cloud-platform/gcp0.png">
+<img src="../images/platforms/google-cloud-platform/gcp0.png">

 This will pull up the `Create an Instance` page - name the instance something relevant to this project, following your naming convention of choice. In addition, select a region and zone that is close to your physical location. For this instance, we will use the base suggested image.

-<img src="../images/quickstart/google-cloud-platform/gcp1.png">
+<img src="../images/platforms/google-cloud-platform/gcp1.png">

 Under `Identity and API Access`, click `Allow full access to all Cloud APIs`. Scroll down to `Firewall` and click `Allow HTTPS traffic` and `Allow HTTP traffic`.

-<img src="../images/quickstart/google-cloud-platform/gcp2.png">
+<img src="../images/platforms/google-cloud-platform/gcp2.png">

 Scroll down to the bottom and click `Create` to create and deploy the VM.

@@ -28,7 +28,7 @@ Congrats you’ve created your VM instance!

 On the Compute Engine Dashboard, click on the VM for this project. Under `Details`, click `SSH` and select `Open in browser window`.

-<img src="../images/quickstart/google-cloud-platform/gcp3.png">
+<img src="../images/platforms/google-cloud-platform/gcp3.png">

 This will give you a terminal into the VM that we will use to install Coder.

@@ -50,7 +50,7 @@ First, edit the `coder.env` file to enable `CODER_TUNNEL` by setting the value t
 sudo vim /etc/coder.d/coder.env
 ```

-<img src="../images/quickstart/google-cloud-platform/gcp4.png">
+<img src="../images/platforms/google-cloud-platform/gcp4.png">

 Exit vim and run the following command to start Coder as a system service:

@@ -64,7 +64,7 @@ The following command shows the Coder service's logs, including the Access URL.
 journalctl -u coder.service -b
 ```

-<img src="../images/quickstart/google-cloud-platform/gcp5.png">
+<img src="../images/platforms/google-cloud-platform/gcp5.png">

 In this instance, Coder can be accessed at the URL `https://fcca2f3bfc9d2e3bf1b9feb50e723448.pit-1.try.coder.app`.

@@ -80,7 +80,7 @@ Fill out the prompts and be sure to save use email and password. This is your ad

 First, run `coder template init` to create your first template. You’ll be given a list of prefabricated templates. This tutorial shows you how to create a Linux based template on GCP.

-<img src="../images/quickstart/google-cloud-platform/gcp6.png">
+<img src="../images/platforms/google-cloud-platform/gcp6.png">

 Select the `Develop in Linux on Google Cloud`, then `cd ./gcp-linux`.

@@ -94,7 +94,7 @@ It will ask for your `project-id`, which you can find on the home page of your G

 Given it’s your first time setting up Coder, it may give an error that will look like the following:

-<img src="../images/quickstart/google-cloud-platform/gcp7.png">
+<img src="../images/platforms/google-cloud-platform/gcp7.png">

 In the error message will be a link. In this case, the URL is `https://console.developes.google.com/apis/api/iam.googles.com/overview:?project=1073148106645`. Copy the respective URL from your error message, and visit it via your browser. It may ask you to enable `Identity and Access Management (IAM) API`.

@@ -102,7 +102,7 @@ Click `enable` and wait as the API initializes for your account.

 Once initialized, click create credentials in the upper right-hand corner. Select the `Compute Engine API` from the dropdown, and select `Application Data` under `What data will you be accessing?`. In addition, select `Yes, I’m using one or more` under `Are you planning on using this API with Compute Engine, Kubernetes Engine, App Engine, or Cloud Functions?`.

-<img src="../images/quickstart/google-cloud-platform/gcp8.png">
+<img src="../images/platforms/google-cloud-platform/gcp8.png">

 Back in your GCP terminal, run the `coder templates create` one more time.

@@ -0,0 +1,26 @@
+# Guide: Coder on Kubernetes
+
+Coder's control plane and/or workspaces can be deployed on Kubernetes.
+
+## Installation
+
+Refer to our [Helm install docs](../install/kubernetes.md) to deploy Coder on Kubernetes. The default helm values will provision the following:
+
+- Coder control plane (as a `Deployment`)
+- ServiceAccount + Role + RoleBinding to provision pods + PVCS in the current namespace (used for Kubernetes workspaces)
+- LoadBalancer to access control plane
+
+## Kubernetes templates
+
+From the dashboard, import the Kubernetes starter template:
+
+![Kubernetes starter template](../images/platforms/kubernetes/starter-template.png)
+
+In the next screen, set the following template variables:
+
+- use_kubeconfig: `false` (The ServiceAccount will authorize Coder to create pods on your cluster)
+- `namespace`: `coder` (or whatever namespace you deployed Coder on)
+
+![Variables for Kubernetes template](../images/platforms/kubernetes/template-variables.png)
+
+> If you deployed Coder on another platform besides Kubernetes, you can set `use_kubeconfig: true` for Coder to read the config from your VM, for example.
@@ -0,0 +1,11 @@
+# Other platforms
+
+Coder is highly extensible and is not limited to the platforms outlined in these docs. The control plane can be provisioned on any VM or container compute, and workspaces can include any Terraform resource. See our [architecture diagram](./about/architecture.md) for more details.
+
+The following resources may help as you're deploying Coder.
+
+- [Coder packages: one-click install on cloud providers](https://github.com/coder/packages)
+- [Run Coder as a system service](../install/packages.md)
+- [Deploy Coder offline](../enterprise/offline.md)
+- [Supported resources (Terraform registry)](https://registry.terraform.io)
+- [Writing custom templates](../templates.md)
@@ -1,9 +0,0 @@
-# Quickstart
-
-Quickstarts are the fastest way to try Coder. We'll walk you through installation and adding your first template and workspace.
-
-First, pick a platform:
-
-<children>
-  This page is rendered on https://coder.com/docs/coder-oss/latest/quickstart. Refer to the other documents in the `install/` directory for per-platform instructions.
-</children>