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 e172ca1c14bc1..46f5e135feb57 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,68 +1,97 @@ # 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 -## 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 1 CPU core 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` or `.rpm`: +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 ``` -### Your First Workspace +Use `coder start --help` to get a complete list of flags and environment +variables. -In a new terminal, create a new project (eg. Develop in Linux on Google Cloud): +### Your first workspace -``` -$ coder templates init -$ coder templates create +In a new terminal, create a template (e.g., a template to **Develop in Linux on +Google Cloud**): + +```bash +coder templates init +coder templates create ``` -Create a new workspace and SSH in: +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 ``` -### Working with Projects +### Modifying templates -You can edit the Terraform from a sample project: +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 + +- [About Coder](./about.md#about-coder) + - [Why remote development](about.md#why-remote-development) + - [Why Coder](about.md#why-coder) + - [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) + - [Variables](./templates.md#variables) +- [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) + - [Workspace lifecycle](./workspaces.md#workspace-lifecycle) + - [Updating workspaces](./workspaces.md#updating-workspaces) + ## Contributing Read the [contributing docs](./CONTRIBUTING.md). - 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 new file mode 100644 index 0000000000000..68e8662cb1dab --- /dev/null +++ b/docs/about.md @@ -0,0 +1,79 @@ +# 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 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). + +## Why remote development + +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: + +- **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) + +- **Easier environment management:** Tools such as Terraform, nix, Docker, + devcontainers, and so on make developer onboarding and the troubleshooting of + development environments easier + +- **Increase security:** Centralize source code and other data onto private + servers or cloud services instead of local developer machines + +- **Improved compatibility:** Remote workspaces share infrastructure + configuration with other development, staging, and production environments, + reducing configuration drift + +- **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 + +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 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 with AWS EC2, +Azure, Google Cloud, Kubernetes, and more. + +## What Coder is *not* + +- Coder is not an infrastructure as code (IaC) platform. Terraform is the first + IaC *provisioner* in Coder, allowing Coder admins to define Terraform + resources as Coder workspaces. + +- 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 supports common editors, such as VS + Code, vim, and JetBrains, over HTTPS or SSH. + +- 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 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/) + +[^2]: slack.engineering: [Development environments at Slack](https://slack.engineering/development-environments-at-slack) diff --git a/docs/templates.md b/docs/templates.md new file mode 100644 index 0000000000000..14bc39726c60f --- /dev/null +++ b/docs/templates.md @@ -0,0 +1,58 @@ +# Templates + +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. + +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 [sample template](../examples/), but you can +modify the templates 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 +``` + +> We recommend source controlling your templates. + +## Persistent and ephemeral resources + +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 | +| :--------------------------- | :--------- | +| google_compute_disk.home_dir | persistent | +| kubernetes_pod.dev | ephemeral | +| └─ nodejs (linux, amd64) | | +| api_token.backend | ephemeral | + +When a workspace is deleted, all resources are destroyed. + +## Parameters + +Templates often contain *parameters*. In Coder, there are two types of parameters: + +- **Admin parameters** 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 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". + +--- + +Next: [Workspaces](./workspaces.md) diff --git a/docs/workspaces.md b/docs/workspaces.md new file mode 100644 index 0000000000000..8da4bfa789b10 --- /dev/null +++ b/docs/workspaces.md @@ -0,0 +1,76 @@ +# Workspaces + +Workspaces contain the IDEs, dependencies, and configuration information needed +for software development. + +## Create workspaces + +Each Coder user has their own workspaces created from [shared +templates](./templates.md): + +```sh +# create a workspace from the template; specify any variables +coder workspaces create + +# show the resources behind the workspace, and how to connect +coder workspaces show +``` + +## Connect with SSH + +Once you've added your workspaces 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, 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) + - IntelliJ IDEA + - CLion + - GoLand + - PyCharm + - Rider + - RubyMine + - WebStorm + +## Workspace lifecycle + +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. + +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, 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 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 template version. +The workspace will be stopped and started: + +```sh +coder workspaces update +```