mirror of https://github.com/coder/coder.git
feat: initial docs pages (#1107)
* docs structure and edits to getting started * draft for about page * skeleton for concepts page * attempt at explaining templates * left-align tables * add best practices and variables * update structrure * update structure * templates are shared * workspaces docs * remove coming soon * fix typos * docs structure and edits to getting started * draft for about page * skeleton for concepts page * attempt at explaining templates * left-align tables * add best practices and variables * update structrure * update structure * templates are shared * workspaces docs * remove coming soon * fix typos * fix typos * Update docs/about.md Co-authored-by: Joe Previte <jjprevite@gmail.com> * remove line breaks between bullets * rename variables to parameters * reduce limits * chore: edit text * revert some changes, fix footnotes Co-authored-by: Katie Horne <katie@coder.com> Co-authored-by: Joe Previte <jjprevite@gmail.com>
This commit is contained in:
Ben Potter
GitHub
parent
603b7da413
commit
22668c388c
|
|
@ -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
|
||||
### Avoid 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.
|
||||
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.
|
||||
|
||||
## Review
|
||||
## Reviews
|
||||
|
||||
> Taken from [Go's review philosophy](https://go.dev/doc/contribute#reviews).
|
||||
> The following information has been borrowed from [Go's review
|
||||
> philosophy](https://go.dev/doc/contribute#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.
|
||||
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).
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -1,68 +1,97 @@
|
|||
# Coder
|
||||
|
||||
[](https://github.com/coder/coder/discussions) [](https://coder.com/community) [](https://twitter.com/coderhq) [](https://codecov.io/gh/coder/coder)
|
||||
[](https://github.com/coder/coder/discussions)
|
||||
[](https://coder.com/community)
|
||||
[](https://twitter.com/coderhq)
|
||||
[](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://<username>@<host>/<database>?password=<password>" \
|
||||
CODER_PG_CONNECTION_URL="postgres://<username>@<host>/<database>?password=<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).
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
@ -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 <template-name>/main.tf
|
||||
|
||||
# add the template to Coder deployment
|
||||
coder templates <create/update> <template-name>
|
||||
```
|
||||
|
||||
> 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)
|
||||
|
|
@ -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 <workspace-name>
|
||||
|
||||
# show the resources behind the workspace, and how to connect
|
||||
coder workspaces show <workspace-name>
|
||||
```
|
||||
|
||||
## 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.<workspace-name>
|
||||
```
|
||||
|
||||
## 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 <workspace-name>` 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 <workspace-name>
|
||||
```
|
||||
Loading…
Reference in New Issue