From eba2d489e8d8491e2a7fe2987ce06c05e7dab4eb Mon Sep 17 00:00:00 2001 From: Ben Date: Fri, 22 Apr 2022 20:32:47 +0000 Subject: [PATCH 01/31] docs structure and edits to getting started --- docs/README.md | 34 +++++++++++++++++++++++++++------- 1 file changed, 27 insertions(+), 7 deletions(-) diff --git a/docs/README.md b/docs/README.md index ed986f655f1ce..d4a2d77745ebc 100644 --- a/docs/README.md +++ b/docs/README.md @@ -10,9 +10,10 @@ Provision remote development environments with Terraform. - Start writing code with a single command - Use one of many [examples](./examples) to get started -## Getting Started +## Installing Coder -Install [the latest release](https://github.com/coder/coder/releases). +Install [the latest release](https://github.com/coder/coder/releases) on a system with +at least 2 CPU cores and 2 GB RAM. To tinker, start with dev-mode (all data is in-memory, and is destroyed on exit): @@ -27,7 +28,7 @@ $ CODER_PG_CONNECTION_URL="postgres://@/?password= Date: Fri, 22 Apr 2022 20:33:12 +0000 Subject: [PATCH 02/31] draft for about page --- docs/about.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 docs/about.md diff --git a/docs/about.md b/docs/about.md new file mode 100644 index 0000000000000..cc0def5bc6d5a --- /dev/null +++ b/docs/about.md @@ -0,0 +1,48 @@ +# About Coder + +Coder is an open source platform for creating and managing developer workspaces on your preferred clouds and servers. + +By building on top of common development inferfaces (SSH) and infrastructure tools (Terraform), Coder aims to make the process of **provisioning** and **accessing** remote workspaces approachable for organizations of various sizes and stages of cloud-native maturity. + +> ⚠️ Coder v2 is in alpha and not ready for production use. You may be interested in [Coder v1](https://coder.com/docs) or [code-server](https://github.com/cdr/code-server). + +## Why remote development + +Migrating from local developer machines to remote servers is an increasingly common solution for developers[^1] and organizations[^2] alike. Remote development has a number of benefits: + +- Speed: Server-grade compute speeds up operations in software development such as IDE loads, compiles, builds, and running large apps (monolyths or many microservices). + +- Environment management: Onboarding & troubleshooting development environments is automated using tools such as Terraform, nix, Docker, devcontainers, etc. + +- Security: Source code and other data can be centralized on private servers or cloud, instead of local developer machines. + +- Compatability: Remote workspaces share infrastructure configuration with other developer, staging, and production environments, reducing configuration drift. + +- Accessibility: Devices such as light notebooks, Chromebooks, and iPads connect to remote workspaces via browser-based IDEs or remote IDE extensions. + +## Why Coder? + +The added layer of infrastructure control is a key differentiator from Coder v1 and other remote IDE platforms. This gives admins the ability to: + +- support ARM, Windows, Linux, and MacOS workspaces +- modify pod/container spec: add disks, manage network policy, environment variables +- use VM/dedicated workspaces: develop with Kernel features, container knowledge not required +- enable persistant workspaces: just like a local machine, but faster and in the cloud + +Coder includes [production-ready templates](./examples) for use on Kubernetes, AWS EC2, Google Cloud, Azure, and more. + +## What Coder is not + +- Coder is an infrastructure as code (IaC) platform. Terraform is the first IaC *provisioner* in Coder. As a result, Coder admins can define any Terraform resources can as Coder workspaces. + +- Coder is not a DevOps/CI platform. Coder workspaces can follow best practices for cloud workloads, but Coder is not responsible for how you define or deploy the software you write. + +- Coder is not an online IDE. Instead, Coder has strong support for common editors such as VS Code, vim, and JetBrains, over HTTPS or SSH. + +- Coder is not a collaboration platform. You can continue using git and IDE extensions for pull requests, code reviews, and pair programming. + +- Coder is not SaaS/fully-managed. Install Coder on your cloud (AWS, GCP, Azure) or datacenter. + +[^1]: alexellis.io: [The Internet is my computer](https://blog.alexellis.io/the-internet-is-my-computer/) + +[^2]: slack.engineering: [Development environments at Slack](https://slack.engineering/development-environments-at-slack) From 8cb6a88a2e9be339df92cc1ac7e435949f32477f Mon Sep 17 00:00:00 2001 From: Ben Date: Fri, 22 Apr 2022 20:33:16 +0000 Subject: [PATCH 03/31] skeleton for concepts page --- docs/concepts.md | 8 ++++++++ 1 file changed, 8 insertions(+) create mode 100644 docs/concepts.md diff --git a/docs/concepts.md b/docs/concepts.md new file mode 100644 index 0000000000000..cd48bbbbc8cf0 --- /dev/null +++ b/docs/concepts.md @@ -0,0 +1,8 @@ +# Coder Concepts + + +## Templates + +Coder admins have the ability to create, update, and delete *templates*. Templates are the blueprint for developer workspaces. + +## Workspaces From 4c1b76703d57e780d44c8d3ae211962998a10218 Mon Sep 17 00:00:00 2001 From: Ben Date: Sun, 24 Apr 2022 17:32:10 +0000 Subject: [PATCH 04/31] attempt at explaining templates --- docs/concepts.md | 52 ++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 50 insertions(+), 2 deletions(-) diff --git a/docs/concepts.md b/docs/concepts.md index cd48bbbbc8cf0..1082a7788c0fb 100644 --- a/docs/concepts.md +++ b/docs/concepts.md @@ -1,8 +1,56 @@ # Coder Concepts - ## Templates -Coder admins have the ability to create, update, and delete *templates*. Templates are the blueprint for developer workspaces. +Coder admins manage *templates* to define the infrastructure behind workspaces. A Coder deployment can have multiple templates for different workloads. + +### ex. "Frontend" Template + +| Resource name | Status | +| ----------------------- | ---------- | +| Kubernetes pod (NodeJS) | ephemeral | +| API token (Backend) | ephemeral | +| Disk (Source code) | persistant | + +### ex. "Data Science" Template + +| Resource name | Status | +| -------------------------------------- | ---------- | +| Kubernetes pod (pyCharm + JupyterLab) | ephemeral | +| Readonly volume mount (shared dataset) | persistant | + +### ex. "MacOS" Template + +| Resource name | Status | +| ------------------ | ---------- | +| MacOS VM | ephemeral | +| Disk (source code) | persistant | + +### ex. "Linux Debugging" Template + +| Resource name | Status | +| ------------------------ | ---------- | +| EC2 VM (Debian 11.3 AMI) | persistant | + +### Templates are managed via the CLI + +Admins can use Coder's production-ready examples, or create/modify templates with standard Terraform. + +```sh +# start from an example template +coder templates init + +# optional: modify the template +vim /main.tf + +# add the template to Coder +coder templates +``` ## Workspaces + +Coder users create *workspaces* to get a remote development environment. Depending on the template, + + + + From d5f5116de70892dae0853d7be9eb714f4b77d881 Mon Sep 17 00:00:00 2001 From: Ben Date: Sun, 24 Apr 2022 17:39:03 +0000 Subject: [PATCH 05/31] left-align tables --- docs/concepts.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/concepts.md b/docs/concepts.md index 1082a7788c0fb..72635d4f78c27 100644 --- a/docs/concepts.md +++ b/docs/concepts.md @@ -7,7 +7,7 @@ Coder admins manage *templates* to define the infrastructure behind workspaces. ### ex. "Frontend" Template | Resource name | Status | -| ----------------------- | ---------- | +| :---------------------- | :--------- | | Kubernetes pod (NodeJS) | ephemeral | | API token (Backend) | ephemeral | | Disk (Source code) | persistant | @@ -15,21 +15,21 @@ Coder admins manage *templates* to define the infrastructure behind workspaces. ### ex. "Data Science" Template | Resource name | Status | -| -------------------------------------- | ---------- | +| :------------------------------------- | :--------- | | Kubernetes pod (pyCharm + JupyterLab) | ephemeral | | Readonly volume mount (shared dataset) | persistant | ### ex. "MacOS" Template | Resource name | Status | -| ------------------ | ---------- | +| :----------------- | :--------- | | MacOS VM | ephemeral | | Disk (source code) | persistant | ### ex. "Linux Debugging" Template | Resource name | Status | -| ------------------------ | ---------- | +| :----------------------- | :--------- | | EC2 VM (Debian 11.3 AMI) | persistant | ### Templates are managed via the CLI From de9f3afd2c2cbe497a18125a9f2561459cdfb81d Mon Sep 17 00:00:00 2001 From: Ben Date: Sun, 24 Apr 2022 18:05:20 +0000 Subject: [PATCH 06/31] add best practices and variables --- docs/concepts.md | 37 ++++++++++++++++++++++++++----------- 1 file changed, 26 insertions(+), 11 deletions(-) diff --git a/docs/concepts.md b/docs/concepts.md index 72635d4f78c27..2d123428819b0 100644 --- a/docs/concepts.md +++ b/docs/concepts.md @@ -2,11 +2,11 @@ ## Templates -Coder admins manage *templates* to define the infrastructure behind workspaces. A Coder deployment can have multiple templates for different workloads. +Coder admins manage *templates* to define the infrastructure behind workspaces. A Coder deployment can have templates for different workloads. ### ex. "Frontend" Template -| Resource name | Status | +| Resource | Type | | :---------------------- | :--------- | | Kubernetes pod (NodeJS) | ephemeral | | API token (Backend) | ephemeral | @@ -14,43 +14,58 @@ Coder admins manage *templates* to define the infrastructure behind workspaces. ### ex. "Data Science" Template -| Resource name | Status | +| Resource | Type | | :------------------------------------- | :--------- | | Kubernetes pod (pyCharm + JupyterLab) | ephemeral | | Readonly volume mount (shared dataset) | persistant | ### ex. "MacOS" Template -| Resource name | Status | +| Resource | Type | | :----------------- | :--------- | | MacOS VM | ephemeral | | Disk (source code) | persistant | ### ex. "Linux Debugging" Template -| Resource name | Status | +| Resource | Type | | :----------------------- | :--------- | | EC2 VM (Debian 11.3 AMI) | persistant | -### Templates are managed via the CLI +### Ephemeral vs persistant + +Coder supports ephemeral and persistant resources in workspaces. Ephemeral resources will be destroyed when a workspace is stopped/not in use. Persistant resources are not. + +When a workspace is deleted, all resources are destroyed. + +### Managing templates Admins can use Coder's production-ready examples, or create/modify templates with standard Terraform. ```sh -# start from an example template +# start from an example coder templates init -# optional: modify the template +# optional: modify the template vim /main.tf -# add the template to Coder +# add the template to Coder deployment coder templates ``` -## Workspaces +If you are commonly editing templates, we recommend source-controlling template code using GitOps/CI pipelines to make changes. -Coder users create *workspaces* to get a remote development environment. Depending on the template, +### Variables +Templates often contain *variables*. In Coder, there are two types of variables. +**Admin variables** are set when a template is being created/updated. These are often cloud secrets, such as a ServiceAccount token. These are annotated with `sensitive = true` in the template code. + +**User variables** are set when a user creates a workspace. They are unique to each workspace, often personalization settings such as preferred region or workspace image. + +## Workspaces + +Coder users create *workspaces* to get a remote development environment. Depending on the template, +### Supported IDEs From 892122c803a61ee78f9451a70bf88ce6403dd329 Mon Sep 17 00:00:00 2001 From: Ben Date: Mon, 25 Apr 2022 14:12:55 +0000 Subject: [PATCH 07/31] update structrure --- docs/README.md | 10 ++++--- docs/concepts.md | 71 ----------------------------------------------- docs/templates.md | 42 ++++++++++++++++++++++++++++ 3 files changed, 48 insertions(+), 75 deletions(-) delete mode 100644 docs/concepts.md create mode 100644 docs/templates.md diff --git a/docs/README.md b/docs/README.md index d4a2d77745ebc..129d704acd851 100644 --- a/docs/README.md +++ b/docs/README.md @@ -73,10 +73,12 @@ Some pages are coming soon. Contributions welcome! - [Why remote development](about.md#why-remote-development) - [Why Coder](about.md#why-coder) - [What Coder is not](about.md#what-coder-is-not) -- Concepts - - Templates - - Workspaces - - Users and Organizations +- [Templates](./templates.md) + - [Managing templates](./templates.md#managing-templates) + - [Persistant and ephemeral resources](./templates.md#persistant-and-ephemeral-resources) + - [Variables](./templates.md#variables) +- Workspaces +- - Guides - Using the Coder CLI - Install Coder on a VM with Caddy + LetsEncrypt diff --git a/docs/concepts.md b/docs/concepts.md deleted file mode 100644 index 2d123428819b0..0000000000000 --- a/docs/concepts.md +++ /dev/null @@ -1,71 +0,0 @@ -# Coder Concepts - -## Templates - -Coder admins manage *templates* to define the infrastructure behind workspaces. A Coder deployment can have templates for different workloads. - -### ex. "Frontend" Template - -| Resource | Type | -| :---------------------- | :--------- | -| Kubernetes pod (NodeJS) | ephemeral | -| API token (Backend) | ephemeral | -| Disk (Source code) | persistant | - -### ex. "Data Science" Template - -| Resource | Type | -| :------------------------------------- | :--------- | -| Kubernetes pod (pyCharm + JupyterLab) | ephemeral | -| Readonly volume mount (shared dataset) | persistant | - -### ex. "MacOS" Template - -| Resource | Type | -| :----------------- | :--------- | -| MacOS VM | ephemeral | -| Disk (source code) | persistant | - -### ex. "Linux Debugging" Template - -| Resource | Type | -| :----------------------- | :--------- | -| EC2 VM (Debian 11.3 AMI) | persistant | - -### Ephemeral vs persistant - -Coder supports ephemeral and persistant resources in workspaces. Ephemeral resources will be destroyed when a workspace is stopped/not in use. Persistant resources are not. - -When a workspace is deleted, all resources are destroyed. - -### Managing templates - -Admins can use Coder's production-ready examples, or create/modify templates with standard Terraform. - -```sh -# start from an example -coder templates init - -# optional: modify the template -vim /main.tf - -# add the template to Coder deployment -coder templates -``` - -If you are commonly editing templates, we recommend source-controlling template code using GitOps/CI pipelines to make changes. - -### Variables - -Templates often contain *variables*. In Coder, there are two types of variables. - -**Admin variables** are set when a template is being created/updated. These are often cloud secrets, such as a ServiceAccount token. These are annotated with `sensitive = true` in the template code. - -**User variables** are set when a user creates a workspace. They are unique to each workspace, often personalization settings such as preferred region or workspace image. - -## Workspaces - -Coder users create *workspaces* to get a remote development environment. Depending on the template, - -### Supported IDEs - diff --git a/docs/templates.md b/docs/templates.md new file mode 100644 index 0000000000000..e314f31477902 --- /dev/null +++ b/docs/templates.md @@ -0,0 +1,42 @@ +# Templates + +Coder admins manage *templates* to define the infrastructure behind workspaces. A Coder deployment can have templates for different workloads. + +## Managing templates + +Coder provides production-ready template [examples](../examples/), but they can be modified with Terraform. + +```sh +# start from an example +coder templates init + +# optional: modify the template +vim /main.tf + +# add the template to Coder deployment +coder templates +``` + +If you are commonly editing templates, we recommend source-controlling template code using GitOps/CI pipelines to make changes. + +## Persistant and ephemeral resources + +Coder supports ephemeral and persistant resources in workspaces. Ephemeral resources are be destroyed when a workspace is not in use (stopped). Persistant resources remain. See how this works for an example "frontend" template: + +| Resource | Type | +| :--------------------------- | :--------- | +| google_compute_disk.home_dir | persistent | +| kubernetes_pod.dev | ephemeral | +| └─ nodejs (linux, amd64) | | +| api_token.backend | ephemeral | + +When a workspace is deleted, all related resources are destroyed. + +## Variables + +Templates often contain *variables*. In Coder, there are two types of variables. + +**Admin variables** are set when a template is being created/updated. These are often cloud secrets, such as a ServiceAccount token. These are annotated with `sensitive = true` in the template code. + +**User variables** are set when a user creates a workspace. They are unique to each workspace, often personalization settings such as preferred region or workspace image. + From c52698204e44b8573cb9363a25c2e6edcf059233 Mon Sep 17 00:00:00 2001 From: Ben Date: Mon, 25 Apr 2022 15:22:59 +0000 Subject: [PATCH 08/31] update structure --- docs/README.md | 5 +++-- docs/about.md | 4 ++++ docs/templates.md | 5 ++++- docs/workspaces.md | 5 +++++ 4 files changed, 16 insertions(+), 3 deletions(-) create mode 100644 docs/workspaces.md diff --git a/docs/README.md b/docs/README.md index 129d704acd851..6761547dc0a73 100644 --- a/docs/README.md +++ b/docs/README.md @@ -77,8 +77,9 @@ Some pages are coming soon. Contributions welcome! - [Managing templates](./templates.md#managing-templates) - [Persistant and ephemeral resources](./templates.md#persistant-and-ephemeral-resources) - [Variables](./templates.md#variables) -- Workspaces -- +- [Workspaces](./workspaces.md) + - [Managing workspaces](./workspaces.md) + - [Editors and IDEs](./workspaces.md#editors-and-ides) - Guides - Using the Coder CLI - Install Coder on a VM with Caddy + LetsEncrypt diff --git a/docs/about.md b/docs/about.md index cc0def5bc6d5a..7de9d3c162b3c 100644 --- a/docs/about.md +++ b/docs/about.md @@ -43,6 +43,10 @@ Coder includes [production-ready templates](./examples) for use on Kubernetes, A - Coder is not SaaS/fully-managed. Install Coder on your cloud (AWS, GCP, Azure) or datacenter. +--- + +Next: [Templates](./templates.md) + [^1]: alexellis.io: [The Internet is my computer](https://blog.alexellis.io/the-internet-is-my-computer/) [^2]: slack.engineering: [Development environments at Slack](https://slack.engineering/development-environments-at-slack) diff --git a/docs/templates.md b/docs/templates.md index e314f31477902..dc0a016033215 100644 --- a/docs/templates.md +++ b/docs/templates.md @@ -1,6 +1,6 @@ # Templates -Coder admins manage *templates* to define the infrastructure behind workspaces. A Coder deployment can have templates for different workloads. +Coder admins manage *templates* to define the infrastructure behind workspaces. A Coder deployment can have multiple templates for different workloads, such as "frontend development," "windows development," etc. ## Managing templates @@ -40,3 +40,6 @@ Templates often contain *variables*. In Coder, there are two types of variables. **User variables** are set when a user creates a workspace. They are unique to each workspace, often personalization settings such as preferred region or workspace image. +--- + +Next: [Workspaces](./workspaces.md) diff --git a/docs/workspaces.md b/docs/workspaces.md new file mode 100644 index 0000000000000..6039b4ddb3c43 --- /dev/null +++ b/docs/workspaces.md @@ -0,0 +1,5 @@ +# Workspaces + +Coder users create workspaces + +## Managing workspaces From 68da32ef58fdc3720d175f4c227b490b521c295b Mon Sep 17 00:00:00 2001 From: Ben Date: Mon, 25 Apr 2022 15:33:36 +0000 Subject: [PATCH 09/31] templates are shared --- docs/templates.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/templates.md b/docs/templates.md index dc0a016033215..d182a5e00b4fe 100644 --- a/docs/templates.md +++ b/docs/templates.md @@ -2,6 +2,8 @@ Coder admins manage *templates* to define the infrastructure behind workspaces. A Coder deployment can have multiple templates for different workloads, such as "frontend development," "windows development," etc. +Templates are shared and updates can be rolled out, or users can manually update their workspaces. + ## Managing templates Coder provides production-ready template [examples](../examples/), but they can be modified with Terraform. From 808767eac10494580c164237a294e1d0bde1d725 Mon Sep 17 00:00:00 2001 From: Ben Date: Mon, 25 Apr 2022 17:04:15 +0000 Subject: [PATCH 10/31] workspaces docs --- docs/README.md | 13 +++++------ docs/templates.md | 6 ++--- docs/workspaces.md | 58 ++++++++++++++++++++++++++++++++++++++++++++-- 3 files changed, 65 insertions(+), 12 deletions(-) diff --git a/docs/README.md b/docs/README.md index 6761547dc0a73..a7943c40d70b8 100644 --- a/docs/README.md +++ b/docs/README.md @@ -74,16 +74,15 @@ Some pages are coming soon. Contributions welcome! - [Why Coder](about.md#why-coder) - [What Coder is not](about.md#what-coder-is-not) - [Templates](./templates.md) - - [Managing templates](./templates.md#managing-templates) - - [Persistant and ephemeral resources](./templates.md#persistant-and-ephemeral-resources) + - [Manage templates](./templates.md#manage-templates) + - [Persistent and ephemeral resources](./templates.md#persistent-and-ephemeral-resources) - [Variables](./templates.md#variables) - [Workspaces](./workspaces.md) - - [Managing workspaces](./workspaces.md) + - [Create workspaces](./workspaces.md#create-workspaces) + - [Connect with SSH](./workspaces.md#connect-with-ssh) - [Editors and IDEs](./workspaces.md#editors-and-ides) -- Guides - - Using the Coder CLI - - Install Coder on a VM with Caddy + LetsEncrypt - - Building templates in Coder + - [Workspace lifecycle](./workspaces.md#workspace-lifecycle) + - [Updating workspaces](./workspaces.md#updating-workspaces) ## Contributing diff --git a/docs/templates.md b/docs/templates.md index d182a5e00b4fe..aa803ca56ebeb 100644 --- a/docs/templates.md +++ b/docs/templates.md @@ -4,7 +4,7 @@ Coder admins manage *templates* to define the infrastructure behind workspaces. Templates are shared and updates can be rolled out, or users can manually update their workspaces. -## Managing templates +## Manage templates Coder provides production-ready template [examples](../examples/), but they can be modified with Terraform. @@ -21,9 +21,9 @@ coder templates If you are commonly editing templates, we recommend source-controlling template code using GitOps/CI pipelines to make changes. -## Persistant and ephemeral resources +## Persistent and ephemeral resources -Coder supports ephemeral and persistant resources in workspaces. Ephemeral resources are be destroyed when a workspace is not in use (stopped). Persistant resources remain. See how this works for an example "frontend" template: +Coder supports ephemeral and persistent resources in workspaces. Ephemeral resources are be destroyed when a workspace is not in use (stopped). persistent resources remain. See how this works for an example "frontend" template: | Resource | Type | | :--------------------------- | :--------- | diff --git a/docs/workspaces.md b/docs/workspaces.md index 6039b4ddb3c43..9242aec9d4833 100644 --- a/docs/workspaces.md +++ b/docs/workspaces.md @@ -1,5 +1,59 @@ # Workspaces -Coder users create workspaces +Workspaces contain the dependencies, IDEs, and configuration information needed for software development. -## Managing workspaces +## Create workspaces + +Each Coder user has their own workspaces, created from a shared [template](./templates.md). + +```sh +# create a workspace from template, specify any variables +coder workspaces create + +# show the resources behind the workspace, and how to connect +coder workspaces show +``` + +## Connect with SSH + +Once Coder workspaces are added to your SSH hosts, you can connect from any IDE with remote development support. + +```sh +coder config-ssh + +ssh coder. +``` + +## Editors and IDEs + +The following desktop IDEs have been tested with Coder. Any IDE with SSH support should work! + +- VS Code (with [Remote - SSH](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh) extension) +- JetBrains (with [Gateway](https://www.jetbrains.com/help/idea/remote-development-a.html#launch_gateway) installed) + - IntelliJ IDEA + - CLion + - GoLand + - PyCharm + - Rider + - RubyMine + - WebStorm + +## Workspace lifecycle + +Workspaces in Coder are started and stopped, often based on activity or when a [template update](./templates.md#manage-templates) is available. + +While the exact behavior depends on the template, resources are often destroyed and re-created when a workspace is restarted. For more details, see [persistent and ephemeral resources](./templates.md#persistent-and-ephemeral-resources). + +> ⚠️ To avoid data loss, reference your template documentation to see where to store files, install software, etc. Default templates are documented in [../examples](../examples/). +> +> You can use `coder workspace show ` to see which resources are persistent vs ephemeral. + +When a workspace is deleted, all of the workspace's resources are deleted. + +## Updating workspaces + +Use the following command to update a workspace to the latest version of a template. The workspace will be stopped and started. + +```sh +coder workspaces update +``` From c8f1e25d03589f1c7f7cc59a5674dd533edd8198 Mon Sep 17 00:00:00 2001 From: Ben Date: Mon, 25 Apr 2022 17:09:00 +0000 Subject: [PATCH 11/31] remove coming soon --- docs/README.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/README.md b/docs/README.md index a7943c40d70b8..4ef686bf3a318 100644 --- a/docs/README.md +++ b/docs/README.md @@ -67,8 +67,6 @@ $ coder templates update gcp-linux ## Documentation -Some pages are coming soon. Contributions welcome! - - [About Coder](./about.md#about-coder) - [Why remote development](about.md#why-remote-development) - [Why Coder](about.md#why-coder) From a803f8a09e389bc2c95feef265071aa0b98f2cc9 Mon Sep 17 00:00:00 2001 From: Ben Date: Mon, 25 Apr 2022 17:11:11 +0000 Subject: [PATCH 12/31] fix typos --- docs/about.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/about.md b/docs/about.md index 7de9d3c162b3c..d372e9696e634 100644 --- a/docs/about.md +++ b/docs/about.md @@ -2,7 +2,7 @@ Coder is an open source platform for creating and managing developer workspaces on your preferred clouds and servers. -By building on top of common development inferfaces (SSH) and infrastructure tools (Terraform), Coder aims to make the process of **provisioning** and **accessing** remote workspaces approachable for organizations of various sizes and stages of cloud-native maturity. +By building on top of common development interfaces (SSH) and infrastructure tools (Terraform), Coder aims to make the process of **provisioning** and **accessing** remote workspaces approachable for organizations of various sizes and stages of cloud-native maturity. > ⚠️ Coder v2 is in alpha and not ready for production use. You may be interested in [Coder v1](https://coder.com/docs) or [code-server](https://github.com/cdr/code-server). @@ -10,13 +10,13 @@ By building on top of common development inferfaces (SSH) and infrastructure too Migrating from local developer machines to remote servers is an increasingly common solution for developers[^1] and organizations[^2] alike. Remote development has a number of benefits: -- Speed: Server-grade compute speeds up operations in software development such as IDE loads, compiles, builds, and running large apps (monolyths or many microservices). +- Speed: Server-grade compute speeds up operations in software development such as IDE loads, compiles, builds, and running large workloads (monolyth or microservice applications). - Environment management: Onboarding & troubleshooting development environments is automated using tools such as Terraform, nix, Docker, devcontainers, etc. - Security: Source code and other data can be centralized on private servers or cloud, instead of local developer machines. -- Compatability: Remote workspaces share infrastructure configuration with other developer, staging, and production environments, reducing configuration drift. +- Compatibility: Remote workspaces share infrastructure configuration with other developer, staging, and production environments, reducing configuration drift. - Accessibility: Devices such as light notebooks, Chromebooks, and iPads connect to remote workspaces via browser-based IDEs or remote IDE extensions. @@ -27,9 +27,9 @@ The added layer of infrastructure control is a key differentiator from Coder v1 - support ARM, Windows, Linux, and MacOS workspaces - modify pod/container spec: add disks, manage network policy, environment variables - use VM/dedicated workspaces: develop with Kernel features, container knowledge not required -- enable persistant workspaces: just like a local machine, but faster and in the cloud +- enable persistent workspaces: just like a local machine, but faster and in the cloud -Coder includes [production-ready templates](./examples) for use on Kubernetes, AWS EC2, Google Cloud, Azure, and more. +Coder includes [production-ready templates](../examples) for use on Kubernetes, AWS EC2, Google Cloud, Azure, and more. ## What Coder is not From 1bb34bd5019863b627336982c5190be2e83af8f1 Mon Sep 17 00:00:00 2001 From: Ben Date: Fri, 22 Apr 2022 20:32:47 +0000 Subject: [PATCH 13/31] docs structure and edits to getting started --- docs/README.md | 34 +++++++++++++++++++++++++++------- 1 file changed, 27 insertions(+), 7 deletions(-) diff --git a/docs/README.md b/docs/README.md index e172ca1c14bc1..6c948b1886046 100644 --- a/docs/README.md +++ b/docs/README.md @@ -10,9 +10,10 @@ Provision remote development environments with Terraform. - Start writing code with a single command - Use one of many [examples](./examples) to get started -## Getting Started +## Installing Coder -Install [the latest release](https://github.com/coder/coder/releases). +Install [the latest release](https://github.com/coder/coder/releases) on a system with +at least 2 CPU cores and 2 GB RAM. To tinker, start with dev-mode (all data is in-memory, and is destroyed on exit): @@ -27,7 +28,7 @@ $ CODER_PG_CONNECTION_URL="postgres://@/?password= Date: Fri, 22 Apr 2022 20:33:12 +0000 Subject: [PATCH 14/31] draft for about page --- docs/about.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 docs/about.md diff --git a/docs/about.md b/docs/about.md new file mode 100644 index 0000000000000..cc0def5bc6d5a --- /dev/null +++ b/docs/about.md @@ -0,0 +1,48 @@ +# About Coder + +Coder is an open source platform for creating and managing developer workspaces on your preferred clouds and servers. + +By building on top of common development inferfaces (SSH) and infrastructure tools (Terraform), Coder aims to make the process of **provisioning** and **accessing** remote workspaces approachable for organizations of various sizes and stages of cloud-native maturity. + +> ⚠️ Coder v2 is in alpha and not ready for production use. You may be interested in [Coder v1](https://coder.com/docs) or [code-server](https://github.com/cdr/code-server). + +## Why remote development + +Migrating from local developer machines to remote servers is an increasingly common solution for developers[^1] and organizations[^2] alike. Remote development has a number of benefits: + +- Speed: Server-grade compute speeds up operations in software development such as IDE loads, compiles, builds, and running large apps (monolyths or many microservices). + +- Environment management: Onboarding & troubleshooting development environments is automated using tools such as Terraform, nix, Docker, devcontainers, etc. + +- Security: Source code and other data can be centralized on private servers or cloud, instead of local developer machines. + +- Compatability: Remote workspaces share infrastructure configuration with other developer, staging, and production environments, reducing configuration drift. + +- Accessibility: Devices such as light notebooks, Chromebooks, and iPads connect to remote workspaces via browser-based IDEs or remote IDE extensions. + +## Why Coder? + +The added layer of infrastructure control is a key differentiator from Coder v1 and other remote IDE platforms. This gives admins the ability to: + +- support ARM, Windows, Linux, and MacOS workspaces +- modify pod/container spec: add disks, manage network policy, environment variables +- use VM/dedicated workspaces: develop with Kernel features, container knowledge not required +- enable persistant workspaces: just like a local machine, but faster and in the cloud + +Coder includes [production-ready templates](./examples) for use on Kubernetes, AWS EC2, Google Cloud, Azure, and more. + +## What Coder is not + +- Coder is an infrastructure as code (IaC) platform. Terraform is the first IaC *provisioner* in Coder. As a result, Coder admins can define any Terraform resources can as Coder workspaces. + +- Coder is not a DevOps/CI platform. Coder workspaces can follow best practices for cloud workloads, but Coder is not responsible for how you define or deploy the software you write. + +- Coder is not an online IDE. Instead, Coder has strong support for common editors such as VS Code, vim, and JetBrains, over HTTPS or SSH. + +- Coder is not a collaboration platform. You can continue using git and IDE extensions for pull requests, code reviews, and pair programming. + +- Coder is not SaaS/fully-managed. Install Coder on your cloud (AWS, GCP, Azure) or datacenter. + +[^1]: alexellis.io: [The Internet is my computer](https://blog.alexellis.io/the-internet-is-my-computer/) + +[^2]: slack.engineering: [Development environments at Slack](https://slack.engineering/development-environments-at-slack) From 0485c6cc3551b39f9b27031efefec6f2abaf9dac Mon Sep 17 00:00:00 2001 From: Ben Date: Fri, 22 Apr 2022 20:33:16 +0000 Subject: [PATCH 15/31] skeleton for concepts page --- docs/concepts.md | 8 ++++++++ 1 file changed, 8 insertions(+) create mode 100644 docs/concepts.md diff --git a/docs/concepts.md b/docs/concepts.md new file mode 100644 index 0000000000000..cd48bbbbc8cf0 --- /dev/null +++ b/docs/concepts.md @@ -0,0 +1,8 @@ +# Coder Concepts + + +## Templates + +Coder admins have the ability to create, update, and delete *templates*. Templates are the blueprint for developer workspaces. + +## Workspaces From 0e1bc577a9cb17ecd20d331038721db2c5145a91 Mon Sep 17 00:00:00 2001 From: Ben Date: Sun, 24 Apr 2022 17:32:10 +0000 Subject: [PATCH 16/31] attempt at explaining templates --- docs/concepts.md | 52 ++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 50 insertions(+), 2 deletions(-) diff --git a/docs/concepts.md b/docs/concepts.md index cd48bbbbc8cf0..1082a7788c0fb 100644 --- a/docs/concepts.md +++ b/docs/concepts.md @@ -1,8 +1,56 @@ # Coder Concepts - ## Templates -Coder admins have the ability to create, update, and delete *templates*. Templates are the blueprint for developer workspaces. +Coder admins manage *templates* to define the infrastructure behind workspaces. A Coder deployment can have multiple templates for different workloads. + +### ex. "Frontend" Template + +| Resource name | Status | +| ----------------------- | ---------- | +| Kubernetes pod (NodeJS) | ephemeral | +| API token (Backend) | ephemeral | +| Disk (Source code) | persistant | + +### ex. "Data Science" Template + +| Resource name | Status | +| -------------------------------------- | ---------- | +| Kubernetes pod (pyCharm + JupyterLab) | ephemeral | +| Readonly volume mount (shared dataset) | persistant | + +### ex. "MacOS" Template + +| Resource name | Status | +| ------------------ | ---------- | +| MacOS VM | ephemeral | +| Disk (source code) | persistant | + +### ex. "Linux Debugging" Template + +| Resource name | Status | +| ------------------------ | ---------- | +| EC2 VM (Debian 11.3 AMI) | persistant | + +### Templates are managed via the CLI + +Admins can use Coder's production-ready examples, or create/modify templates with standard Terraform. + +```sh +# start from an example template +coder templates init + +# optional: modify the template +vim /main.tf + +# add the template to Coder +coder templates +``` ## Workspaces + +Coder users create *workspaces* to get a remote development environment. Depending on the template, + + + + From 57d4d0f8728ec2bc19b7a7f5592d396039122105 Mon Sep 17 00:00:00 2001 From: Ben Date: Sun, 24 Apr 2022 17:39:03 +0000 Subject: [PATCH 17/31] left-align tables --- docs/concepts.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/concepts.md b/docs/concepts.md index 1082a7788c0fb..72635d4f78c27 100644 --- a/docs/concepts.md +++ b/docs/concepts.md @@ -7,7 +7,7 @@ Coder admins manage *templates* to define the infrastructure behind workspaces. ### ex. "Frontend" Template | Resource name | Status | -| ----------------------- | ---------- | +| :---------------------- | :--------- | | Kubernetes pod (NodeJS) | ephemeral | | API token (Backend) | ephemeral | | Disk (Source code) | persistant | @@ -15,21 +15,21 @@ Coder admins manage *templates* to define the infrastructure behind workspaces. ### ex. "Data Science" Template | Resource name | Status | -| -------------------------------------- | ---------- | +| :------------------------------------- | :--------- | | Kubernetes pod (pyCharm + JupyterLab) | ephemeral | | Readonly volume mount (shared dataset) | persistant | ### ex. "MacOS" Template | Resource name | Status | -| ------------------ | ---------- | +| :----------------- | :--------- | | MacOS VM | ephemeral | | Disk (source code) | persistant | ### ex. "Linux Debugging" Template | Resource name | Status | -| ------------------------ | ---------- | +| :----------------------- | :--------- | | EC2 VM (Debian 11.3 AMI) | persistant | ### Templates are managed via the CLI From fc48d53635543ab499447378a9ceec5a2e7be7ff Mon Sep 17 00:00:00 2001 From: Ben Date: Sun, 24 Apr 2022 18:05:20 +0000 Subject: [PATCH 18/31] add best practices and variables --- docs/concepts.md | 37 ++++++++++++++++++++++++++----------- 1 file changed, 26 insertions(+), 11 deletions(-) diff --git a/docs/concepts.md b/docs/concepts.md index 72635d4f78c27..2d123428819b0 100644 --- a/docs/concepts.md +++ b/docs/concepts.md @@ -2,11 +2,11 @@ ## Templates -Coder admins manage *templates* to define the infrastructure behind workspaces. A Coder deployment can have multiple templates for different workloads. +Coder admins manage *templates* to define the infrastructure behind workspaces. A Coder deployment can have templates for different workloads. ### ex. "Frontend" Template -| Resource name | Status | +| Resource | Type | | :---------------------- | :--------- | | Kubernetes pod (NodeJS) | ephemeral | | API token (Backend) | ephemeral | @@ -14,43 +14,58 @@ Coder admins manage *templates* to define the infrastructure behind workspaces. ### ex. "Data Science" Template -| Resource name | Status | +| Resource | Type | | :------------------------------------- | :--------- | | Kubernetes pod (pyCharm + JupyterLab) | ephemeral | | Readonly volume mount (shared dataset) | persistant | ### ex. "MacOS" Template -| Resource name | Status | +| Resource | Type | | :----------------- | :--------- | | MacOS VM | ephemeral | | Disk (source code) | persistant | ### ex. "Linux Debugging" Template -| Resource name | Status | +| Resource | Type | | :----------------------- | :--------- | | EC2 VM (Debian 11.3 AMI) | persistant | -### Templates are managed via the CLI +### Ephemeral vs persistant + +Coder supports ephemeral and persistant resources in workspaces. Ephemeral resources will be destroyed when a workspace is stopped/not in use. Persistant resources are not. + +When a workspace is deleted, all resources are destroyed. + +### Managing templates Admins can use Coder's production-ready examples, or create/modify templates with standard Terraform. ```sh -# start from an example template +# start from an example coder templates init -# optional: modify the template +# optional: modify the template vim /main.tf -# add the template to Coder +# add the template to Coder deployment coder templates ``` -## Workspaces +If you are commonly editing templates, we recommend source-controlling template code using GitOps/CI pipelines to make changes. -Coder users create *workspaces* to get a remote development environment. Depending on the template, +### Variables +Templates often contain *variables*. In Coder, there are two types of variables. +**Admin variables** are set when a template is being created/updated. These are often cloud secrets, such as a ServiceAccount token. These are annotated with `sensitive = true` in the template code. + +**User variables** are set when a user creates a workspace. They are unique to each workspace, often personalization settings such as preferred region or workspace image. + +## Workspaces + +Coder users create *workspaces* to get a remote development environment. Depending on the template, +### Supported IDEs From 361decc2e23d3aff4c01c17b79a5b9757f9986c1 Mon Sep 17 00:00:00 2001 From: Ben Date: Mon, 25 Apr 2022 14:12:55 +0000 Subject: [PATCH 19/31] update structrure --- docs/README.md | 10 ++++--- docs/concepts.md | 71 ----------------------------------------------- docs/templates.md | 42 ++++++++++++++++++++++++++++ 3 files changed, 48 insertions(+), 75 deletions(-) delete mode 100644 docs/concepts.md create mode 100644 docs/templates.md diff --git a/docs/README.md b/docs/README.md index 6c948b1886046..e616d291d99f5 100644 --- a/docs/README.md +++ b/docs/README.md @@ -73,10 +73,12 @@ Some pages are coming soon. Contributions welcome! - [Why remote development](about.md#why-remote-development) - [Why Coder](about.md#why-coder) - [What Coder is not](about.md#what-coder-is-not) -- Concepts - - Templates - - Workspaces - - Users and Organizations +- [Templates](./templates.md) + - [Managing templates](./templates.md#managing-templates) + - [Persistant and ephemeral resources](./templates.md#persistant-and-ephemeral-resources) + - [Variables](./templates.md#variables) +- Workspaces +- - Guides - Using the Coder CLI - Install Coder on a VM with Caddy + LetsEncrypt diff --git a/docs/concepts.md b/docs/concepts.md deleted file mode 100644 index 2d123428819b0..0000000000000 --- a/docs/concepts.md +++ /dev/null @@ -1,71 +0,0 @@ -# Coder Concepts - -## Templates - -Coder admins manage *templates* to define the infrastructure behind workspaces. A Coder deployment can have templates for different workloads. - -### ex. "Frontend" Template - -| Resource | Type | -| :---------------------- | :--------- | -| Kubernetes pod (NodeJS) | ephemeral | -| API token (Backend) | ephemeral | -| Disk (Source code) | persistant | - -### ex. "Data Science" Template - -| Resource | Type | -| :------------------------------------- | :--------- | -| Kubernetes pod (pyCharm + JupyterLab) | ephemeral | -| Readonly volume mount (shared dataset) | persistant | - -### ex. "MacOS" Template - -| Resource | Type | -| :----------------- | :--------- | -| MacOS VM | ephemeral | -| Disk (source code) | persistant | - -### ex. "Linux Debugging" Template - -| Resource | Type | -| :----------------------- | :--------- | -| EC2 VM (Debian 11.3 AMI) | persistant | - -### Ephemeral vs persistant - -Coder supports ephemeral and persistant resources in workspaces. Ephemeral resources will be destroyed when a workspace is stopped/not in use. Persistant resources are not. - -When a workspace is deleted, all resources are destroyed. - -### Managing templates - -Admins can use Coder's production-ready examples, or create/modify templates with standard Terraform. - -```sh -# start from an example -coder templates init - -# optional: modify the template -vim /main.tf - -# add the template to Coder deployment -coder templates -``` - -If you are commonly editing templates, we recommend source-controlling template code using GitOps/CI pipelines to make changes. - -### Variables - -Templates often contain *variables*. In Coder, there are two types of variables. - -**Admin variables** are set when a template is being created/updated. These are often cloud secrets, such as a ServiceAccount token. These are annotated with `sensitive = true` in the template code. - -**User variables** are set when a user creates a workspace. They are unique to each workspace, often personalization settings such as preferred region or workspace image. - -## Workspaces - -Coder users create *workspaces* to get a remote development environment. Depending on the template, - -### Supported IDEs - diff --git a/docs/templates.md b/docs/templates.md new file mode 100644 index 0000000000000..e314f31477902 --- /dev/null +++ b/docs/templates.md @@ -0,0 +1,42 @@ +# Templates + +Coder admins manage *templates* to define the infrastructure behind workspaces. A Coder deployment can have templates for different workloads. + +## Managing templates + +Coder provides production-ready template [examples](../examples/), but they can be modified with Terraform. + +```sh +# start from an example +coder templates init + +# optional: modify the template +vim /main.tf + +# add the template to Coder deployment +coder templates +``` + +If you are commonly editing templates, we recommend source-controlling template code using GitOps/CI pipelines to make changes. + +## Persistant and ephemeral resources + +Coder supports ephemeral and persistant resources in workspaces. Ephemeral resources are be destroyed when a workspace is not in use (stopped). Persistant resources remain. See how this works for an example "frontend" template: + +| Resource | Type | +| :--------------------------- | :--------- | +| google_compute_disk.home_dir | persistent | +| kubernetes_pod.dev | ephemeral | +| └─ nodejs (linux, amd64) | | +| api_token.backend | ephemeral | + +When a workspace is deleted, all related resources are destroyed. + +## Variables + +Templates often contain *variables*. In Coder, there are two types of variables. + +**Admin variables** are set when a template is being created/updated. These are often cloud secrets, such as a ServiceAccount token. These are annotated with `sensitive = true` in the template code. + +**User variables** are set when a user creates a workspace. They are unique to each workspace, often personalization settings such as preferred region or workspace image. + From 950ee8577843167978d2460140727c92939554e4 Mon Sep 17 00:00:00 2001 From: Ben Date: Mon, 25 Apr 2022 15:22:59 +0000 Subject: [PATCH 20/31] update structure --- docs/README.md | 5 +++-- docs/about.md | 4 ++++ docs/templates.md | 5 ++++- docs/workspaces.md | 5 +++++ 4 files changed, 16 insertions(+), 3 deletions(-) create mode 100644 docs/workspaces.md diff --git a/docs/README.md b/docs/README.md index e616d291d99f5..008e8a657f90f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -77,8 +77,9 @@ Some pages are coming soon. Contributions welcome! - [Managing templates](./templates.md#managing-templates) - [Persistant and ephemeral resources](./templates.md#persistant-and-ephemeral-resources) - [Variables](./templates.md#variables) -- Workspaces -- +- [Workspaces](./workspaces.md) + - [Managing workspaces](./workspaces.md) + - [Editors and IDEs](./workspaces.md#editors-and-ides) - Guides - Using the Coder CLI - Install Coder on a VM with Caddy + LetsEncrypt diff --git a/docs/about.md b/docs/about.md index cc0def5bc6d5a..7de9d3c162b3c 100644 --- a/docs/about.md +++ b/docs/about.md @@ -43,6 +43,10 @@ Coder includes [production-ready templates](./examples) for use on Kubernetes, A - Coder is not SaaS/fully-managed. Install Coder on your cloud (AWS, GCP, Azure) or datacenter. +--- + +Next: [Templates](./templates.md) + [^1]: alexellis.io: [The Internet is my computer](https://blog.alexellis.io/the-internet-is-my-computer/) [^2]: slack.engineering: [Development environments at Slack](https://slack.engineering/development-environments-at-slack) diff --git a/docs/templates.md b/docs/templates.md index e314f31477902..dc0a016033215 100644 --- a/docs/templates.md +++ b/docs/templates.md @@ -1,6 +1,6 @@ # Templates -Coder admins manage *templates* to define the infrastructure behind workspaces. A Coder deployment can have templates for different workloads. +Coder admins manage *templates* to define the infrastructure behind workspaces. A Coder deployment can have multiple templates for different workloads, such as "frontend development," "windows development," etc. ## Managing templates @@ -40,3 +40,6 @@ Templates often contain *variables*. In Coder, there are two types of variables. **User variables** are set when a user creates a workspace. They are unique to each workspace, often personalization settings such as preferred region or workspace image. +--- + +Next: [Workspaces](./workspaces.md) diff --git a/docs/workspaces.md b/docs/workspaces.md new file mode 100644 index 0000000000000..6039b4ddb3c43 --- /dev/null +++ b/docs/workspaces.md @@ -0,0 +1,5 @@ +# Workspaces + +Coder users create workspaces + +## Managing workspaces From afac7eee38d2931efd46da288e51e35ae7702c4d Mon Sep 17 00:00:00 2001 From: Ben Date: Mon, 25 Apr 2022 15:33:36 +0000 Subject: [PATCH 21/31] templates are shared --- docs/templates.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/templates.md b/docs/templates.md index dc0a016033215..d182a5e00b4fe 100644 --- a/docs/templates.md +++ b/docs/templates.md @@ -2,6 +2,8 @@ Coder admins manage *templates* to define the infrastructure behind workspaces. A Coder deployment can have multiple templates for different workloads, such as "frontend development," "windows development," etc. +Templates are shared and updates can be rolled out, or users can manually update their workspaces. + ## Managing templates Coder provides production-ready template [examples](../examples/), but they can be modified with Terraform. From e67dabbe8a1308226d5e70fcaa29016db6cd7c5d Mon Sep 17 00:00:00 2001 From: Ben Date: Mon, 25 Apr 2022 17:04:15 +0000 Subject: [PATCH 22/31] workspaces docs --- docs/README.md | 13 +++++------ docs/templates.md | 6 ++--- docs/workspaces.md | 58 ++++++++++++++++++++++++++++++++++++++++++++-- 3 files changed, 65 insertions(+), 12 deletions(-) diff --git a/docs/README.md b/docs/README.md index 008e8a657f90f..1863eaf59f0e5 100644 --- a/docs/README.md +++ b/docs/README.md @@ -74,16 +74,15 @@ Some pages are coming soon. Contributions welcome! - [Why Coder](about.md#why-coder) - [What Coder is not](about.md#what-coder-is-not) - [Templates](./templates.md) - - [Managing templates](./templates.md#managing-templates) - - [Persistant and ephemeral resources](./templates.md#persistant-and-ephemeral-resources) + - [Manage templates](./templates.md#manage-templates) + - [Persistent and ephemeral resources](./templates.md#persistent-and-ephemeral-resources) - [Variables](./templates.md#variables) - [Workspaces](./workspaces.md) - - [Managing workspaces](./workspaces.md) + - [Create workspaces](./workspaces.md#create-workspaces) + - [Connect with SSH](./workspaces.md#connect-with-ssh) - [Editors and IDEs](./workspaces.md#editors-and-ides) -- Guides - - Using the Coder CLI - - Install Coder on a VM with Caddy + LetsEncrypt - - Building templates in Coder + - [Workspace lifecycle](./workspaces.md#workspace-lifecycle) + - [Updating workspaces](./workspaces.md#updating-workspaces) ## Contributing diff --git a/docs/templates.md b/docs/templates.md index d182a5e00b4fe..aa803ca56ebeb 100644 --- a/docs/templates.md +++ b/docs/templates.md @@ -4,7 +4,7 @@ Coder admins manage *templates* to define the infrastructure behind workspaces. Templates are shared and updates can be rolled out, or users can manually update their workspaces. -## Managing templates +## Manage templates Coder provides production-ready template [examples](../examples/), but they can be modified with Terraform. @@ -21,9 +21,9 @@ coder templates If you are commonly editing templates, we recommend source-controlling template code using GitOps/CI pipelines to make changes. -## Persistant and ephemeral resources +## Persistent and ephemeral resources -Coder supports ephemeral and persistant resources in workspaces. Ephemeral resources are be destroyed when a workspace is not in use (stopped). Persistant resources remain. See how this works for an example "frontend" template: +Coder supports ephemeral and persistent resources in workspaces. Ephemeral resources are be destroyed when a workspace is not in use (stopped). persistent resources remain. See how this works for an example "frontend" template: | Resource | Type | | :--------------------------- | :--------- | diff --git a/docs/workspaces.md b/docs/workspaces.md index 6039b4ddb3c43..9242aec9d4833 100644 --- a/docs/workspaces.md +++ b/docs/workspaces.md @@ -1,5 +1,59 @@ # Workspaces -Coder users create workspaces +Workspaces contain the dependencies, IDEs, and configuration information needed for software development. -## Managing workspaces +## Create workspaces + +Each Coder user has their own workspaces, created from a shared [template](./templates.md). + +```sh +# create a workspace from template, specify any variables +coder workspaces create + +# show the resources behind the workspace, and how to connect +coder workspaces show +``` + +## Connect with SSH + +Once Coder workspaces are added to your SSH hosts, you can connect from any IDE with remote development support. + +```sh +coder config-ssh + +ssh coder. +``` + +## Editors and IDEs + +The following desktop IDEs have been tested with Coder. Any IDE with SSH support should work! + +- VS Code (with [Remote - SSH](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh) extension) +- JetBrains (with [Gateway](https://www.jetbrains.com/help/idea/remote-development-a.html#launch_gateway) installed) + - IntelliJ IDEA + - CLion + - GoLand + - PyCharm + - Rider + - RubyMine + - WebStorm + +## Workspace lifecycle + +Workspaces in Coder are started and stopped, often based on activity or when a [template update](./templates.md#manage-templates) is available. + +While the exact behavior depends on the template, resources are often destroyed and re-created when a workspace is restarted. For more details, see [persistent and ephemeral resources](./templates.md#persistent-and-ephemeral-resources). + +> ⚠️ To avoid data loss, reference your template documentation to see where to store files, install software, etc. Default templates are documented in [../examples](../examples/). +> +> You can use `coder workspace show ` to see which resources are persistent vs ephemeral. + +When a workspace is deleted, all of the workspace's resources are deleted. + +## Updating workspaces + +Use the following command to update a workspace to the latest version of a template. The workspace will be stopped and started. + +```sh +coder workspaces update +``` From 325c46ce475f26cf7950228db04e6a3b1d4b24c6 Mon Sep 17 00:00:00 2001 From: Ben Date: Mon, 25 Apr 2022 17:09:00 +0000 Subject: [PATCH 23/31] remove coming soon --- docs/README.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/README.md b/docs/README.md index 1863eaf59f0e5..7d3ecfd3c7305 100644 --- a/docs/README.md +++ b/docs/README.md @@ -67,8 +67,6 @@ $ coder templates update gcp-linux ## Documentation -Some pages are coming soon. Contributions welcome! - - [About Coder](./about.md#about-coder) - [Why remote development](about.md#why-remote-development) - [Why Coder](about.md#why-coder) From e37e4a4c7b7706c5b498475ebf94ba1b7d10a90d Mon Sep 17 00:00:00 2001 From: Ben Date: Mon, 25 Apr 2022 17:11:11 +0000 Subject: [PATCH 24/31] fix typos --- docs/about.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/about.md b/docs/about.md index 7de9d3c162b3c..d372e9696e634 100644 --- a/docs/about.md +++ b/docs/about.md @@ -2,7 +2,7 @@ Coder is an open source platform for creating and managing developer workspaces on your preferred clouds and servers. -By building on top of common development inferfaces (SSH) and infrastructure tools (Terraform), Coder aims to make the process of **provisioning** and **accessing** remote workspaces approachable for organizations of various sizes and stages of cloud-native maturity. +By building on top of common development interfaces (SSH) and infrastructure tools (Terraform), Coder aims to make the process of **provisioning** and **accessing** remote workspaces approachable for organizations of various sizes and stages of cloud-native maturity. > ⚠️ Coder v2 is in alpha and not ready for production use. You may be interested in [Coder v1](https://coder.com/docs) or [code-server](https://github.com/cdr/code-server). @@ -10,13 +10,13 @@ By building on top of common development inferfaces (SSH) and infrastructure too Migrating from local developer machines to remote servers is an increasingly common solution for developers[^1] and organizations[^2] alike. Remote development has a number of benefits: -- Speed: Server-grade compute speeds up operations in software development such as IDE loads, compiles, builds, and running large apps (monolyths or many microservices). +- Speed: Server-grade compute speeds up operations in software development such as IDE loads, compiles, builds, and running large workloads (monolyth or microservice applications). - Environment management: Onboarding & troubleshooting development environments is automated using tools such as Terraform, nix, Docker, devcontainers, etc. - Security: Source code and other data can be centralized on private servers or cloud, instead of local developer machines. -- Compatability: Remote workspaces share infrastructure configuration with other developer, staging, and production environments, reducing configuration drift. +- Compatibility: Remote workspaces share infrastructure configuration with other developer, staging, and production environments, reducing configuration drift. - Accessibility: Devices such as light notebooks, Chromebooks, and iPads connect to remote workspaces via browser-based IDEs or remote IDE extensions. @@ -27,9 +27,9 @@ The added layer of infrastructure control is a key differentiator from Coder v1 - support ARM, Windows, Linux, and MacOS workspaces - modify pod/container spec: add disks, manage network policy, environment variables - use VM/dedicated workspaces: develop with Kernel features, container knowledge not required -- enable persistant workspaces: just like a local machine, but faster and in the cloud +- enable persistent workspaces: just like a local machine, but faster and in the cloud -Coder includes [production-ready templates](./examples) for use on Kubernetes, AWS EC2, Google Cloud, Azure, and more. +Coder includes [production-ready templates](../examples) for use on Kubernetes, AWS EC2, Google Cloud, Azure, and more. ## What Coder is not From 3bf7d4f13855d3aee6991dec8c01114a3f37be95 Mon Sep 17 00:00:00 2001 From: Ben Date: Mon, 25 Apr 2022 22:35:43 +0000 Subject: [PATCH 25/31] fix typos --- docs/README.md | 2 +- docs/about.md | 2 +- docs/templates.md | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/README.md b/docs/README.md index 7d3ecfd3c7305..8bf796ee5db39 100644 --- a/docs/README.md +++ b/docs/README.md @@ -40,7 +40,7 @@ Reference `coder start --help` for a complete list of flags and environment vari ### Your First Workspace -In a new terminal, create a new template (eg. Develop in Linux on Google Cloud): +In a new terminal, create a template (eg. Develop in Linux on Google Cloud): ``` $ coder templates init diff --git a/docs/about.md b/docs/about.md index d372e9696e634..bd0345e532351 100644 --- a/docs/about.md +++ b/docs/about.md @@ -33,7 +33,7 @@ Coder includes [production-ready templates](../examples) for use on Kubernetes, ## What Coder is not -- Coder is an infrastructure as code (IaC) platform. Terraform is the first IaC *provisioner* in Coder. As a result, Coder admins can define any Terraform resources can as Coder workspaces. +- Coder is not an infrastructure as code (IaC) platform. Terraform is the first IaC *provisioner* in Coder. As a result, Coder admins can define any Terraform resources can as Coder workspaces. - Coder is not a DevOps/CI platform. Coder workspaces can follow best practices for cloud workloads, but Coder is not responsible for how you define or deploy the software you write. diff --git a/docs/templates.md b/docs/templates.md index aa803ca56ebeb..ead3834c84532 100644 --- a/docs/templates.md +++ b/docs/templates.md @@ -23,7 +23,7 @@ If you are commonly editing templates, we recommend source-controlling template ## Persistent and ephemeral resources -Coder supports ephemeral and persistent resources in workspaces. Ephemeral resources are be destroyed when a workspace is not in use (stopped). persistent resources remain. See how this works for an example "frontend" template: +Coder supports ephemeral and persistent resources in workspaces. Ephemeral resources are destroyed when a workspace is not in use (stopped). persistent resources remain. See how this works for an example "frontend" template: | Resource | Type | | :--------------------------- | :--------- | @@ -32,7 +32,7 @@ Coder supports ephemeral and persistent resources in workspaces. Ephemeral resou | └─ nodejs (linux, amd64) | | | api_token.backend | ephemeral | -When a workspace is deleted, all related resources are destroyed. +When a workspace is deleted, all resources are destroyed. ## Variables From ebcb866547ee6d1a5ff689239793b7f7f5849892 Mon Sep 17 00:00:00 2001 From: Ben Potter Date: Mon, 25 Apr 2022 22:31:57 -0500 Subject: [PATCH 26/31] Update docs/about.md Co-authored-by: Joe Previte --- docs/about.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/about.md b/docs/about.md index bd0345e532351..e14e69fae9f42 100644 --- a/docs/about.md +++ b/docs/about.md @@ -10,7 +10,7 @@ By building on top of common development interfaces (SSH) and infrastructure too Migrating from local developer machines to remote servers is an increasingly common solution for developers[^1] and organizations[^2] alike. Remote development has a number of benefits: -- Speed: Server-grade compute speeds up operations in software development such as IDE loads, compiles, builds, and running large workloads (monolyth or microservice applications). +- Speed: Server-grade compute speeds up operations in software development such as IDE loads, compiles, builds, and running large workloads (monolith or microservice applications). - Environment management: Onboarding & troubleshooting development environments is automated using tools such as Terraform, nix, Docker, devcontainers, etc. From 9c182822a546b97dd30098b5829db67207e73a78 Mon Sep 17 00:00:00 2001 From: Ben Date: Tue, 26 Apr 2022 03:33:14 +0000 Subject: [PATCH 27/31] remove line breaks between bullets --- docs/about.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/about.md b/docs/about.md index bd0345e532351..8c4f069e6f7c5 100644 --- a/docs/about.md +++ b/docs/about.md @@ -11,13 +11,9 @@ By building on top of common development interfaces (SSH) and infrastructure too Migrating from local developer machines to remote servers is an increasingly common solution for developers[^1] and organizations[^2] alike. Remote development has a number of benefits: - Speed: Server-grade compute speeds up operations in software development such as IDE loads, compiles, builds, and running large workloads (monolyth or microservice applications). - - Environment management: Onboarding & troubleshooting development environments is automated using tools such as Terraform, nix, Docker, devcontainers, etc. - - Security: Source code and other data can be centralized on private servers or cloud, instead of local developer machines. - - Compatibility: Remote workspaces share infrastructure configuration with other developer, staging, and production environments, reducing configuration drift. - - Accessibility: Devices such as light notebooks, Chromebooks, and iPads connect to remote workspaces via browser-based IDEs or remote IDE extensions. ## Why Coder? From 3e4318aa796ba91c9dee57f3bbeeb1abc57af321 Mon Sep 17 00:00:00 2001 From: Ben Date: Tue, 26 Apr 2022 03:33:48 +0000 Subject: [PATCH 28/31] rename variables to parameters --- docs/templates.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/templates.md b/docs/templates.md index ead3834c84532..b1aa746cc0c29 100644 --- a/docs/templates.md +++ b/docs/templates.md @@ -34,13 +34,13 @@ Coder supports ephemeral and persistent resources in workspaces. Ephemeral resou When a workspace is deleted, all resources are destroyed. -## Variables +## Parameters -Templates often contain *variables*. In Coder, there are two types of variables. +Templates often contain *parameters*. In Coder, there are two types of parameters. -**Admin variables** are set when a template is being created/updated. These are often cloud secrets, such as a ServiceAccount token. These are annotated with `sensitive = true` in the template code. +**Admin parameters** are set when a template is being created/updated. These are often cloud secrets, such as a ServiceAccount token. These are annotated with `sensitive = true` in the template code. -**User variables** are set when a user creates a workspace. They are unique to each workspace, often personalization settings such as preferred region or workspace image. +**User parameters** are set when a user creates a workspace. They are unique to each workspace, often personalization settings such as preferred region or workspace image. --- From 8c93ae2b644886eb513224d4ff2f768c9861dd93 Mon Sep 17 00:00:00 2001 From: Ben Date: Tue, 26 Apr 2022 03:34:11 +0000 Subject: [PATCH 29/31] reduce limits --- docs/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/README.md b/docs/README.md index 8bf796ee5db39..886226658d401 100644 --- a/docs/README.md +++ b/docs/README.md @@ -13,7 +13,7 @@ Provision remote development environments with Terraform. ## Installing Coder Install [the latest release](https://github.com/coder/coder/releases) on a system with -at least 2 CPU cores and 2 GB RAM. +at least 1 CPU core and 2 GB RAM. To tinker, start with dev-mode (all data is in-memory, and is destroyed on exit): From 2ef477d1722608ca53c6cc4a95a9e11567a81c78 Mon Sep 17 00:00:00 2001 From: Katie Horne Date: Tue, 26 Apr 2022 08:10:56 -0500 Subject: [PATCH 30/31] chore: edit text --- docs/CONTRIBUTING.md | 57 +++++++++++++++++--------------- docs/README.md | 66 +++++++++++++++++++++---------------- docs/SECURITY.md | 4 +-- docs/about.md | 78 ++++++++++++++++++++++++++++++-------------- docs/templates.md | 27 ++++++++++----- docs/workspaces.md | 41 ++++++++++++++++------- 6 files changed, 172 insertions(+), 101 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 98627e9fb6d86..322b7f9aaf198 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -1,48 +1,53 @@ + # Contributing ## Requirements -`coder` requires Go 1.18+, Node 14+, and GNU Make. +Coder requires Go 1.18+, Node 14+, and GNU Make. -### Development Workflow +### Development workflow -The following `make` commands and scripts used in development: +Use the following `make` commands and scripts in development: - `make bin` builds binaries - `make install` installs binaries to `$GOPATH/bin` - `make test` -- `make release` dry-runs a new release -- `./develop.sh` hot-reloads for frontend development +- `make release` dry runs a new release +- `./develop.sh` hot reloads for front-end development ## Styling -### Go Style +### Use Go style -Contributions must adhere to [Effective Go](https://go.dev/doc/effective_go). Linting rules should -be preferred over documenting styles (run ours with `make lint`); humans are error prone! +Contributions must adhere to the guidelines outlined in [Effective +Go](https://go.dev/doc/effective_go). We prefer linting rules over documenting +styles (run ours with `make lint`); humans are error-prone! -Read [Go's Code Review Comments Wiki](https://github.com/golang/go/wiki/CodeReviewComments) to find +Read [Go's Code Review Comments +Wiki](https://github.com/golang/go/wiki/CodeReviewComments) for information on common comments made during reviews of Go code. -#### No Unused Packages - -Coders write packages that are used during implementation. It's difficult to validate whether an -abstraction is valid until it's checked against an implementation. This results in a larger -changeset but provides reviewers with an educated perspective on the contribution. +### Avoid unused packages -## Review +Coder writes packages that are used during implementation. It isn't easy to +validate whether an abstraction is valid until it's checked against an +implementation. This results in a larger changeset, but it provides reviewers +with a holistic perspective regarding the contribution. -> Taken from [Go's review philosophy](https://go.dev/doc/contribute#reviews). +## Reviews -Coders value thorough reviews. Think of each review comment like a ticket: you are expected to -somehow "close" it by acting on it, either by implementing the suggestion or convincing the reviewer -otherwise. +> The following information has been borrowed from [Go's review +> philosophy](https://go.dev/doc/contribute#reviews). -After you update the change, go through the review comments and make sure to reply to every one. You -can click the "Done" button to reply indicating that you've implemented the reviewer's suggestion; -otherwise, click on "Reply" and explain why you have not, or what you have done instead. +Coder values thorough reviews. For each review comment that you receive, please +"close" it by implementing the suggestion or providing an explanation on why the +suggestion isn't the best option. Be sure to do this for each comment; you can +click **Done** to indicate that you've implemented the suggestion, or you can +add a comment explaining why you aren't implementing the suggestion (or what you +chose to implement instead). -It is perfectly normal for changes to go through several round of reviews, with one or more -reviewers making new comments every time and then waiting for an updated change before reviewing -again. All contributors, including experienced maintainers, are subject to the same review cycle; -this process is not meant to be applied selectively or discourage anyone from contribution. +It is perfectly normal for changes to go through several rounds of reviews, with +one or more reviewers making new comments every time, then waiting for an +updated change before reviewing again. All contributors, including those from +maintainers, are subject to the same review cycle; this process is not meant to +be applied selectively or to discourage anyone from contributing. diff --git a/docs/README.md b/docs/README.md index 7d3ecfd3c7305..bc8a374920d99 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,68 +1,77 @@ # Coder -[!["GitHub Discussions"](https://img.shields.io/badge/%20GitHub-%20Discussions-gray.svg?longCache=true&logo=github&colorB=purple)](https://github.com/coder/coder/discussions) [!["Join us on Slack"](https://img.shields.io/badge/join-us%20on%20slack-gray.svg?longCache=true&logo=slack&colorB=brightgreen)](https://coder.com/community) [![Twitter Follow](https://img.shields.io/twitter/follow/CoderHQ?label=%40CoderHQ&style=social)](https://twitter.com/coderhq) [![codecov](https://codecov.io/gh/coder/coder/branch/main/graph/badge.svg?token=TNLW3OAP6G)](https://codecov.io/gh/coder/coder) +[!["GitHub +Discussions"](https://img.shields.io/badge/%20GitHub-%20Discussions-gray.svg?longCache=true&logo=github&colorB=purple)](https://github.com/coder/coder/discussions) +[!["Join us on +Slack"](https://img.shields.io/badge/join-us%20on%20slack-gray.svg?longCache=true&logo=slack&colorB=brightgreen)](https://coder.com/community) +[![Twitter +Follow](https://img.shields.io/twitter/follow/CoderHQ?label=%40CoderHQ&style=social)](https://twitter.com/coderhq) +[![codecov](https://codecov.io/gh/coder/coder/branch/main/graph/badge.svg?token=TNLW3OAP6G)](https://codecov.io/gh/coder/coder) Provision remote development environments with Terraform. ## Highlights -- Automate development environments for Linux, Windows, and MacOS in your cloud +- Automate development environments for Linux, Windows, and macOS - Start writing code with a single command -- Use one of many [examples](./examples) to get started +- Get started quickly using one of the [examples](./examples) provided ## Installing Coder -Install [the latest release](https://github.com/coder/coder/releases) on a system with -at least 2 CPU cores and 2 GB RAM. +Install [the latest release](https://github.com/coder/coder/releases) on a +system with at least 2 CPU cores and 2 GB RAM. -To tinker, start with dev-mode (all data is in-memory, and is destroyed on exit): +To test, start with dev mode (all data is in-memory and is destroyed on exit): ```bash -$ coder server --dev +coder server --dev ``` To run a production deployment with PostgreSQL: ```bash -$ CODER_PG_CONNECTION_URL="postgres://@/?password=" \ +CODER_PG_CONNECTION_URL="postgres://@/?password=" \ coder server ``` -To run as a system service, install with `.deb` (Debian, Ubuntu) or `.rpm` (Fedora, CentOS, RHEL, SUSE): +To run as a system service, install with `.deb` (Debian, Ubuntu) or `.rpm` +(Fedora, CentOS, RHEL, SUSE): ```bash # Edit the configuration! -$ sudo vim /etc/coder.d/coder.env -$ sudo service coder restart +sudo vim /etc/coder.d/coder.env +sudo service coder restart ``` -Reference `coder start --help` for a complete list of flags and environment variables. +Use `coder start --help` to get a complete list of flags and environment +variables. -### Your First Workspace +### Your first workspace -In a new terminal, create a new template (eg. Develop in Linux on Google Cloud): +In a new terminal, create a template (e.g., a template to **Develop in Linux on +Google Cloud**): -``` -$ coder templates init -$ coder templates create +```bash +coder templates init +coder templates create ``` -Create a new workspace and connect via SSH: +Create a workspace and connect to it via SSH: -``` -$ coder workspaces create my-first-workspace -$ coder ssh my-first-workspace +```bash +coder workspaces create my-first-workspace +coder ssh my-first-workspace ``` -### Modifying Templates +### Modifying templates -You can edit the Terraform from a sample template: +You can edit the Terraform template using a sample template: ```sh -$ coder templates init -$ cd gcp-linux/ -$ vim main.tf -$ coder templates update gcp-linux +coder templates init +cd gcp-linux/ +vim main.tf +coder templates update gcp-linux ``` ## Documentation @@ -73,7 +82,8 @@ $ coder templates update gcp-linux - [What Coder is not](about.md#what-coder-is-not) - [Templates](./templates.md) - [Manage templates](./templates.md#manage-templates) - - [Persistent and ephemeral resources](./templates.md#persistent-and-ephemeral-resources) + - [Persistent and ephemeral + resources](./templates.md#persistent-and-ephemeral-resources) - [Variables](./templates.md#variables) - [Workspaces](./workspaces.md) - [Create workspaces](./workspaces.md#create-workspaces) diff --git a/docs/SECURITY.md b/docs/SECURITY.md index 2e2faabacb517..c2aaf31e61a52 100644 --- a/docs/SECURITY.md +++ b/docs/SECURITY.md @@ -1,4 +1,4 @@ # Security Policy -Keeping your code secure is core to what we do. If you find a vulnerability, -please send an email to security@coder.com, and our team will respond to you. +Keeping your code secure is central to what we do. If you find a vulnerability, +please send an email to security@coder.com. diff --git a/docs/about.md b/docs/about.md index d372e9696e634..6c8f22cbd4f5e 100644 --- a/docs/about.md +++ b/docs/about.md @@ -1,52 +1,80 @@ # About Coder -Coder is an open source platform for creating and managing developer workspaces on your preferred clouds and servers. +Coder is an open-source platform that makes it easy for organizations of all +sizes to provision, manage, and access remote developer workspaces that are +hosted using the cloud service of their choice. -By building on top of common development interfaces (SSH) and infrastructure tools (Terraform), Coder aims to make the process of **provisioning** and **accessing** remote workspaces approachable for organizations of various sizes and stages of cloud-native maturity. - -> ⚠️ Coder v2 is in alpha and not ready for production use. You may be interested in [Coder v1](https://coder.com/docs) or [code-server](https://github.com/cdr/code-server). +> ⚠️ Coder v2 is in **alpha** state and is *not* ready for production use. For +> production environments, please consider [Coder v1](https://coder.com/docs) or +> [code-server](https://github.com/cdr/code-server). ## Why remote development -Migrating from local developer machines to remote servers is an increasingly common solution for developers[^1] and organizations[^2] alike. Remote development has a number of benefits: +Migrating from local developer machines to workspaces hosted by cloud services +is an increasingly common solution for developers[^1] and organizations[^2] +alike. There are several benefits, including: -- Speed: Server-grade compute speeds up operations in software development such as IDE loads, compiles, builds, and running large workloads (monolyth or microservice applications). +- **Increased speed:** Server-grade compute speeds up operations in software + development, such as IDE loading, code compilation and building, and the + running of large workloads (such as those for monolith or microservice + applications) -- Environment management: Onboarding & troubleshooting development environments is automated using tools such as Terraform, nix, Docker, devcontainers, etc. +- **Easier environment management:** Tools such as Terraform, nix, Docker, + devcontainers, and so on make developer onboarding and the troubleshooting of + development environments easier -- Security: Source code and other data can be centralized on private servers or cloud, instead of local developer machines. +- **Increase security:** Centralize source code and other data onto private + servers or cloud services instead of local developer machines -- Compatibility: Remote workspaces share infrastructure configuration with other developer, staging, and production environments, reducing configuration drift. +- **Improved compatibility:** Remote workspaces share infrastructure + configuration with other development, staging, and production environments, + reducing configuration drift -- Accessibility: Devices such as light notebooks, Chromebooks, and iPads connect to remote workspaces via browser-based IDEs or remote IDE extensions. +- **Improved accessibility:** Devices such as lightweight notebooks, + Chromebooks, and iPads can connect to remote workspaces via browser-based IDEs + or remote IDE extensions -## Why Coder? +## Why Coder -The added layer of infrastructure control is a key differentiator from Coder v1 and other remote IDE platforms. This gives admins the ability to: +The key difference between Coder v2 and other remote IDE platforms is the added +layer of infrastructure control. This additional layer allows admins to: -- support ARM, Windows, Linux, and MacOS workspaces -- modify pod/container spec: add disks, manage network policy, environment variables -- use VM/dedicated workspaces: develop with Kernel features, container knowledge not required -- enable persistent workspaces: just like a local machine, but faster and in the cloud +- Support ARM, Windows, Linux, and macOS workspaces +- Modify pod/container specs (e.g., adding disks, managing network policies, + setting/updating environment variables) +- Use VM/dedicated workspaces, developing with Kernel features (no container + knowledge required) +- Enable persistent workspaces, which are like local machines, but faster and + hosted by a cloud service -Coder includes [production-ready templates](../examples) for use on Kubernetes, AWS EC2, Google Cloud, Azure, and more. +Coder includes [production-ready templates](../examples) for use with AWS EC2, +Azure, Google Cloud, Kubernetes, and more. -## What Coder is not +## What Coder is *not* -- Coder is an infrastructure as code (IaC) platform. Terraform is the first IaC *provisioner* in Coder. As a result, Coder admins can define any Terraform resources can as Coder workspaces. +- Coder is an infrastructure-as-code (IaC) platform. Terraform is the first IaC + *provisioner* in Coder. As a result, Coder admins can define Terraform + resources as Coder workspaces. -- Coder is not a DevOps/CI platform. Coder workspaces can follow best practices for cloud workloads, but Coder is not responsible for how you define or deploy the software you write. +- Coder is not a DevOps/CI platform. Coder workspaces can follow best practices + for cloud service-based workloads, but Coder is not responsible for how you + define or deploy the software you write. -- Coder is not an online IDE. Instead, Coder has strong support for common editors such as VS Code, vim, and JetBrains, over HTTPS or SSH. +- Coder is not an online IDE. Instead, Coder supports common editors, such as VS + Code, vim, and JetBrains, over HTTPS or SSH. -- Coder is not a collaboration platform. You can continue using git and IDE extensions for pull requests, code reviews, and pair programming. +- Coder is not a collaboration platform. You can use git and dedicated IDE + extensions for pull requests, code reviews, and pair programming. -- Coder is not SaaS/fully-managed. Install Coder on your cloud (AWS, GCP, Azure) or datacenter. +- Coder is not a software-as-a-service/fully-managed offering. You must host + Coder on a cloud service (AWS, Azure, GCP) or your private data center. --- Next: [Templates](./templates.md) -[^1]: alexellis.io: [The Internet is my computer](https://blog.alexellis.io/the-internet-is-my-computer/) +[^1]: alexellis.io: [The Internet is my + computer](https://blog.alexellis.io/the-internet-is-my-computer/) -[^2]: slack.engineering: [Development environments at Slack](https://slack.engineering/development-environments-at-slack) +[^2]: slack.engineering: [Development environments at + Slack](https://slack.engineering/development-environments-at-slack) diff --git a/docs/templates.md b/docs/templates.md index aa803ca56ebeb..a38f8be59aed8 100644 --- a/docs/templates.md +++ b/docs/templates.md @@ -1,12 +1,16 @@ # Templates -Coder admins manage *templates* to define the infrastructure behind workspaces. A Coder deployment can have multiple templates for different workloads, such as "frontend development," "windows development," etc. +Templates define the infrastructure underlying workspaces. Each Coder deployment +can have multiple templates for different workloads, such as ones for front-end +development, Windows development, and so on. -Templates are shared and updates can be rolled out, or users can manually update their workspaces. +Admins of Coder manage templates, including sharing them and rolling out updates +to everybody. Users can also manually update their workspaces. ## Manage templates -Coder provides production-ready template [examples](../examples/), but they can be modified with Terraform. +Coder provides production-ready [sample template](../examples/), but you can +modify the templates with Terraform. ```sh # start from an example @@ -19,11 +23,14 @@ vim /main.tf coder templates ``` -If you are commonly editing templates, we recommend source-controlling template code using GitOps/CI pipelines to make changes. +> We recommend source controlling your templates. ## Persistent and ephemeral resources -Coder supports ephemeral and persistent resources in workspaces. Ephemeral resources are be destroyed when a workspace is not in use (stopped). persistent resources remain. See how this works for an example "frontend" template: +Coder supports both ephemeral and persistent resources in workspaces. Ephemeral +resources are destroyed when a workspace is not in use (e.g., when it is +stopped). Persistent resources remain. See how this works for a sample front-end +template: | Resource | Type | | :--------------------------- | :--------- | @@ -36,11 +43,15 @@ When a workspace is deleted, all related resources are destroyed. ## Variables -Templates often contain *variables*. In Coder, there are two types of variables. +Templates often contain *variables*. In Coder, there are two types of variables: -**Admin variables** are set when a template is being created/updated. These are often cloud secrets, such as a ServiceAccount token. These are annotated with `sensitive = true` in the template code. +- **Admin variables** are set when a template is created/updated. These values + are often cloud secrets, such as a `ServiceAccount` token, and are annotated + with `sensitive = true` in the template code. -**User variables** are set when a user creates a workspace. They are unique to each workspace, often personalization settings such as preferred region or workspace image. +**User variables** are set when a user creates a workspace. They are unique to +each workspace, and they are often personalization settings such as preferred +region or workspace image. --- diff --git a/docs/workspaces.md b/docs/workspaces.md index 9242aec9d4833..8da4bfa789b10 100644 --- a/docs/workspaces.md +++ b/docs/workspaces.md @@ -1,13 +1,15 @@ # Workspaces -Workspaces contain the dependencies, IDEs, and configuration information needed for software development. +Workspaces contain the IDEs, dependencies, and configuration information needed +for software development. ## Create workspaces -Each Coder user has their own workspaces, created from a shared [template](./templates.md). +Each Coder user has their own workspaces created from [shared +templates](./templates.md): ```sh -# create a workspace from template, specify any variables +# create a workspace from the template; specify any variables coder workspaces create # show the resources behind the workspace, and how to connect @@ -16,7 +18,8 @@ coder workspaces show ## Connect with SSH -Once Coder workspaces are added to your SSH hosts, you can connect from any IDE with remote development support. +Once you've added your workspaces to your SSH hosts, you can connect from any +IDE with remote development support: ```sh coder config-ssh @@ -26,10 +29,15 @@ ssh coder. ## Editors and IDEs -The following desktop IDEs have been tested with Coder. Any IDE with SSH support should work! +The following desktop IDEs have been tested with Coder, though any IDE with SSH +support should work! -- VS Code (with [Remote - SSH](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh) extension) -- JetBrains (with [Gateway](https://www.jetbrains.com/help/idea/remote-development-a.html#launch_gateway) installed) +- VS Code (with [Remote - + SSH](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh) + extension) +- JetBrains (with + [Gateway](https://www.jetbrains.com/help/idea/remote-development-a.html#launch_gateway) + installed) - IntelliJ IDEA - CLion - GoLand @@ -40,19 +48,28 @@ The following desktop IDEs have been tested with Coder. Any IDE with SSH support ## Workspace lifecycle -Workspaces in Coder are started and stopped, often based on activity or when a [template update](./templates.md#manage-templates) is available. +Workspaces in Coder are started and stopped, often based on whether there was +any activity or if there was a [template +update](./templates.md#manage-templates) available. -While the exact behavior depends on the template, resources are often destroyed and re-created when a workspace is restarted. For more details, see [persistent and ephemeral resources](./templates.md#persistent-and-ephemeral-resources). +Resources are often destroyed and re-created when a workspace is restarted, +though the exact behavior depends on the template's definitions. For more +information, see [persistent and ephemeral +resources](./templates.md#persistent-and-ephemeral-resources). -> ⚠️ To avoid data loss, reference your template documentation to see where to store files, install software, etc. Default templates are documented in [../examples](../examples/). +> ⚠️ To avoid data loss, refer to your template documentation for information on +> where to store files, install software, etc., so that they persist. Default +> templates are documented in [../examples](../examples/). > -> You can use `coder workspace show ` to see which resources are persistent vs ephemeral. +> You can use `coder workspace show ` to see which resources are +> persistent and which are ephemeral. When a workspace is deleted, all of the workspace's resources are deleted. ## Updating workspaces -Use the following command to update a workspace to the latest version of a template. The workspace will be stopped and started. +Use the following command to update a workspace to the latest template version. +The workspace will be stopped and started: ```sh coder workspaces update From 81435b5cc6410d2867d341a2981e5d5eabdd9366 Mon Sep 17 00:00:00 2001 From: Ben Date: Tue, 26 Apr 2022 16:58:27 +0000 Subject: [PATCH 31/31] revert some changes, fix footnotes --- docs/about.md | 17 ++++++++--------- docs/templates.md | 6 +++--- 2 files changed, 11 insertions(+), 12 deletions(-) diff --git a/docs/about.md b/docs/about.md index 9a73bd8202add..68e8662cb1dab 100644 --- a/docs/about.md +++ b/docs/about.md @@ -1,10 +1,11 @@ # About Coder -Coder is an open-source platform that makes it easy for organizations of all -sizes to provision, manage, and access remote developer workspaces that are -hosted using the cloud service of their choice. +Coder is an open source platform for creating and managing developer workspaces +on your preferred clouds and servers. -> ⚠️ Coder v2 is in **alpha** state and is *not* ready for production use. For +By building on top of common development interfaces (SSH) and infrastructure tools (Terraform), Coder aims to make the process of **provisioning** and **accessing** remote workspaces approachable for organizations of various sizes and stages of cloud-native maturity. + +> ⚠️ Coder v2 is in **alpha** state and is not ready for production use. For > production environments, please consider [Coder v1](https://coder.com/docs) or > [code-server](https://github.com/cdr/code-server). @@ -66,15 +67,13 @@ Azure, Google Cloud, Kubernetes, and more. - Coder is not a collaboration platform. You can use git and dedicated IDE extensions for pull requests, code reviews, and pair programming. -- Coder is not a software-as-a-service/fully-managed offering. You must host +- Coder is not a SaaS/fully-managed offering. You must host Coder on a cloud service (AWS, Azure, GCP) or your private data center. --- Next: [Templates](./templates.md) -[^1]: alexellis.io: [The Internet is my - computer](https://blog.alexellis.io/the-internet-is-my-computer/) +[^1]: alexellis.io: [The Internet is my computer](https://blog.alexellis.io/the-internet-is-my-computer/) -[^2]: slack.engineering: [Development environments at - Slack](https://slack.engineering/development-environments-at-slack) +[^2]: slack.engineering: [Development environments at Slack](https://slack.engineering/development-environments-at-slack) diff --git a/docs/templates.md b/docs/templates.md index e5ded6e33296f..14bc39726c60f 100644 --- a/docs/templates.md +++ b/docs/templates.md @@ -4,7 +4,7 @@ Templates define the infrastructure underlying workspaces. Each Coder deployment can have multiple templates for different workloads, such as ones for front-end development, Windows development, and so on. -Admins of Coder manage templates, including sharing them and rolling out updates +Coder manage templates, including sharing them and rolling out updates to everybody. Users can also manually update their workspaces. ## Manage templates @@ -50,8 +50,8 @@ Templates often contain *parameters*. In Coder, there are two types of parameter with `sensitive = true` in the template code. **User parameters** are set when a user creates a workspace. They are unique to -each workspace, and they are often personalization settings such as preferred -region or workspace image. +each workspace, often personalization settings such as "preferred +region" or "workspace image". ---