diff --git a/docs/README.md b/docs/README.md index b69d731b56179..3593d5b32252b 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,27 +1,99 @@ -# Coder Documentation +# 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). + +## How it works + +Coder workspaces are represented with Terraform. But, no Terraform knowledge is +required to get started. We have a database of pre-made templates built into the +product.

- +

-## Table of Contents - -- [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) - - [Comparison: Coder vs. [product]](./about.md#comparison) -- [Quickstart](./quickstart.md) - - [Creating your first template and workspace](./quickstart.md#creating-your-first-template-and-workspace) - - [Modifying templates](./quickstart.md#modifying-templates) -- [Templates](./templates.md) - - [Manage templates](./templates.md#manage-templates) - - [Persistent and ephemeral - resources](./templates.md#persistent-and-ephemeral-resources) - - [Parameters](./templates.md#parameters) -- [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) +Coder workspaces don't stop at compute. You can add storage buckets, secrets, sidecars +and whatever else Terraform lets you dream up. + +[Learn more about managing infrastructure.](./templates.md) + +## IDE Support + +You can use any Web IDE ([code-server](https://github.com/coder/code-server), [projector](https://github.com/JetBrains/projector-server), [Jupyter](https://jupyter.org/), etc.), [JetBrains Gateway](https://www.jetbrains.com/remote-development/gateway/), [VS Code Remote](https://code.visualstudio.com/docs/remote/ssh-tutorial) or even a file sync such as [mutagen](https://mutagen.io/). + +

+ +

+ +## 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/templates) 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/about.md b/docs/about.md deleted file mode 100644 index 3593d5b32252b..0000000000000 --- a/docs/about.md +++ /dev/null @@ -1,99 +0,0 @@ -# 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). - -## How it works - -Coder workspaces are represented with Terraform. But, no Terraform knowledge is -required to get started. We have a database of pre-made templates built into the -product. - -

- -

- -Coder workspaces don't stop at compute. You can add storage buckets, secrets, sidecars -and whatever else Terraform lets you dream up. - -[Learn more about managing infrastructure.](./templates.md) - -## IDE Support - -You can use any Web IDE ([code-server](https://github.com/coder/code-server), [projector](https://github.com/JetBrains/projector-server), [Jupyter](https://jupyter.org/), etc.), [JetBrains Gateway](https://www.jetbrains.com/remote-development/gateway/), [VS Code Remote](https://code.visualstudio.com/docs/remote/ssh-tutorial) or even a file sync such as [mutagen](https://mutagen.io/). - -

- -

- -## 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/templates) 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/install.md b/docs/install.md index 5f055f7224513..e57a3fac6ca3b 100644 --- a/docs/install.md +++ b/docs/install.md @@ -49,7 +49,6 @@ sudo service coder restart Or run a **temporary deployment** with dev mode (all data is in-memory and destroyed on exit): - ```sh coder server --dev ``` @@ -61,65 +60,65 @@ Coder](https://github.com/coder/coder/releases) installed. 1. Clone the `coder` repository: - ```console - git clone git@github.com:coder/coder.git - ``` + ```console + git clone git@github.com:coder/coder.git + ``` 1. Navigate into the `coder` folder. Coder requires a non-`localhost` access URL - for non-Docker-based examples; if you have a public IP or a domain/reverse - proxy, you can provide this value before running `docker-compose up` to - start the service: + for non-Docker-based examples; if you have a public IP or a domain/reverse + proxy, you can provide this value before running `docker-compose up` to + start the service: - ```console - cd coder - CODER_ACCESS_URL=https://coder.mydomain.com - docker-compose up - ``` + ```console + cd coder + CODER_ACCESS_URL=https://coder.mydomain.com + docker-compose up + ``` - Otherwise, you can start the service: + Otherwise, you can start the service: - ```console - cd coder - docker-compose up - ``` + ```console + cd coder + docker-compose up + ``` - Alternatively, if you would like to start a **temporary deployment**: + Alternatively, if you would like to start a **temporary deployment**: - ```console - docker run --rm -it \ - -e CODER_DEV_MODE=true \ - -v /var/run/docker.sock:/var/run/docker.sock \ - ghcr.io/coder/coder:v0.5.10 - ``` + ```console + docker run --rm -it \ + -e CODER_DEV_MODE=true \ + -v /var/run/docker.sock:/var/run/docker.sock \ + ghcr.io/coder/coder:v0.5.10 + ``` 1. Follow the on-screen instructions to create your first template and workspace -## Manual +## Manual -We publish self-contained .zip and .tar.gz archives in [GitHub releases](https://github.com/coder/coder/releases). The archives bundle `coder` binary. +We publish self-contained .zip and .tar.gz archives in [GitHub releases](https://github.com/coder/coder/releases). The archives bundle `coder` binary. 1. Download the [release archive](https://github.com/coder/coder/releases) appropriate for your operating system 1. Unzip the folder you just downloaded, and move the `coder` executable to a location that's on your `PATH` - ```sh - # ex. MacOS and Linux - mv coder /usr/local/bin - ``` + ```sh + # ex. MacOS and Linux + mv coder /usr/local/bin + ``` - > Windows users: see [this guide](https://answers.microsoft.com/en-us/windows/forum/all/adding-path-variable/97300613-20cb-4d85-8d0e-cc9d3549ba23) for adding folders to `PATH`. + > Windows users: see [this guide](https://answers.microsoft.com/en-us/windows/forum/all/adding-path-variable/97300613-20cb-4d85-8d0e-cc9d3549ba23) for adding folders to `PATH`. 1. Start a Coder server - To run a **temporary deployment**, start with dev mode (all data is in-memory and destroyed on exit): + To run a **temporary deployment**, start with dev mode (all data is in-memory and destroyed on exit): - ```bash - coder server --dev - ``` + ```bash + coder server --dev + ``` - To run a **production deployment** with PostgreSQL: + To run a **production deployment** with PostgreSQL: - ```bash - CODER_PG_CONNECTION_URL="postgres://@/?password=" \ - coder server - ``` + ```bash + CODER_PG_CONNECTION_URL="postgres://@/?password=" \ + coder server + ``` diff --git a/docs/manifest.json b/docs/manifest.json index 846d49d0b8245..0313fbe2d2c32 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -1,17 +1,11 @@ { "versions": ["0.6.2"], "routes": [ - { - "title": "Home", - "description": "How to install and run Coder", - "path": "./README.md", - "icon": "" - }, { "title": "About", "description": "About Coder", - "path": "./about.md", - "icon": "" + "path": "./README.md", + "icon": "" }, { "title": "Installation",