opensource/coder
3
0
Fork 0
mirror of https://github.com/coder/coder.git synced 2026-09-24 15:04:27 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: restructure docs (#14421)

Browse Source 
Closes #13434 
Supersedes #14182

---------

Co-authored-by: Ethan <39577870+ethanndickson@users.noreply.github.com>
Co-authored-by: Ethan Dickson <ethan@coder.com>
Co-authored-by: Ben Potter <ben@coder.com>
Co-authored-by: Stephen Kirby <58410745+stirby@users.noreply.github.com>
Co-authored-by: Stephen Kirby <me@skirby.dev>
Co-authored-by: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com>
Co-authored-by: Edward Angert <EdwardAngert@users.noreply.github.com>
This commit is contained in:
Muhammad Atif Ali
2024-10-05 10:52:04 -05:00
committed by GitHub
co-authored by Ethan Ethan Dickson Ben Potter Stephen Kirby Stephen Kirby EdwardAngert Edward Angert
parent 288df75686
commit 419eba5fb6
298 changed files with 5009 additions and 3889 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/install/1-click.md
-12
View File
@@ -1,12 +0,0 @@
Coder can be installed on many cloud providers using our
[one-click install packages](https://github.com/coder/packages)
| Platform Name | Status | Documentation | Deploy |
| --------------------- | ----------- | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| AWS EC2 | Live ✅ | [Guide: AWS](https://coder.com/docs/platforms/aws) | [Deploy from AWS Marketplace](https://aws.amazon.com/marketplace/pp/prodview-5gxjyur2vc7rg?sr=0-2&ref_=beagle&applicationId=AWSMPContessa) |
| AWS EKS | In progress | [Docs: Coder on Kubernetes](https://coder.com/docs/install/kubernetes) | [Deploy from AWS Marketplace](https://example.com) |
| Google Compute Engine | Live ✅ | [Guide: Google Compute Engine](https://coder.com/docs/platforms/gcp) | [Deploy from GCP Marketplace](https://console.cloud.google.com/marketplace/product/coder-enterprise-market-public/coder-v2) |
| Fly.io | Live ✅ | [Blog: Run Coder on Fly.io](https://coder.com/blog/remote-developer-environments-on-fly-io) | [Deploy Coder on Fly.io](https://coder.com/blog/remote-developer-environments-on-fly-io) |
| Railway.app | Live ✅ | [Blog: Run Coder on Railway.app](https://coder.com/blog/deploy-coder-on-railway-app) | [![Deploy Coder on Railway](https://railway.app/button.svg)](https://railway.app/template/coder?referralCode=tfH8Uw) |
| Heroku | Live ✅ | [Docs: Deploy Coder on Heroku](https://github.com/coder/packages/blob/main/heroku/README.md) | [![Deploy Coder on Heroku](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy?template=https://github.com/coder/packages) |
| Render | Live ✅ | [Docs: Deploy Coder on Render](https://github.com/coder/packages/blob/main/render/README.md) | [![Deploy to Render](https://render.com/images/deploy-to-render-button.svg)](https://render.com/deploy?repo=https://github.com/coder/packages) |
docs/install/cli.md
+60
View File
@@ -0,0 +1,60 @@
# Installing Coder
A single CLI (`coder`) is used for both the Coder server and the client.
We support two release channels: mainline and stable - read the
[Releases](./releases.md) page to learn more about which best suits your team.
<div class="tabs">
## Linux/macOS
Our install script is the fastest way to install Coder on Linux/macOS:
```sh
curl -L https://coder.com/install.sh | sh
```
Refer to [GitHub releases](https://github.com/coder/coder/releases) for
alternate installation methods (e.g. standalone binaries, system packages).
## Windows
> **Important:** If you plan to use the built-in PostgreSQL database, you will
> need to ensure that the
> [Visual C++ Runtime](https://learn.microsoft.com/en-US/cpp/windows/latest-supported-vc-redist#latest-microsoft-visual-c-redistributable-version)
> is installed.
Use [GitHub releases](https://github.com/coder/coder/releases) to download the
Windows installer (`.msi`) or standalone binary (`.exe`).
![Windows setup wizard](../images/install/windows-installer.png)
Alternatively, you can use the
[`winget`](https://learn.microsoft.com/en-us/windows/package-manager/winget/#use-winget)
package manager to install Coder:
```powershell
winget install Coder.Coder
```
</div>
To start the Coder server:
```sh
coder server
```
![Coder install](../images/install/coder-setup.png)
To log in to an existing Coder deployment:
```sh
coder login https://coder.example.com
```
### Next up
- [Create your first template](../tutorials/template-from-scratch.md)
- [Control plane configuration](../admin/setup/index.md)
docs/install/cloud/azure-vm.md
+135
View File
@@ -0,0 +1,135 @@
# Microsoft Azure
This guide shows you how to set up the Coder server on Azure which will
provision Azure-hosted Linux workspaces.
## Requirements
This guide assumes you have full administrator privileges on Azure.
## Create An Azure VM
From the Azure Portal, navigate to the Virtual Machines Dashboard. Click Create,
and select creating a new Azure Virtual machine .
<img src="../../images/platforms/azure/azure1.jpg">
This will bring you to the `Create a virtual machine` page. Select the
subscription group of your choice, or create one if necessary.
Next, name the VM something relevant to this project using the naming convention
of your choice. Change the region to something more appropriate for your current
location. For this tutorial, we will use the base selection of the Ubuntu Gen2
Image and keep the rest of the base settings for this image the same.
<img src="../../images/platforms/azure/azure2.png">
<img src="../../images/platforms/azure/azure3.png">
Up next, under `Inbound port rules` modify the Select `inbound ports` to also
take in `HTTPS` and `HTTP`.
<img src="../../images/platforms/azure/azure4.png">
The set up for the image is complete at this stage. Click `Review and Create` -
review the information and click `Create`. A popup will appear asking you to
download the key pair for the server. Click
`Download private key and create resource` and place it into a folder of your
choice on your local system.
<img src="../../images/platforms/azure/azure5.png">
Click `Return to create a virtual machine`. Your VM will start up!
<img src="../../images/platforms/azure/azure6.png">
Click `Go to resource` in the virtual machine and copy the public IP address.
You will need it to SSH into the virtual machine via your local machine.
Follow
[these instructions](https://learn.microsoft.com/en-us/azure/virtual-machines/linux-vm-connect?tabs=Linux)
to SSH into the virtual machine. Once on the VM, you can run and install Coder
using your method of choice. For the fastest install, we recommend running Coder
as a system service.
## Install Coder
For this instance, we will run Coder as a system service, however you can run
Coder a multitude of different ways. You can learn more about those
[here](https://coder.com/docs/coder-oss/latest/install).
In the Azure VM instance, run the following command to install Coder
```shell
curl -fsSL https://coder.com/install.sh | sh
```
## Run Coder
Run the following command to start Coder as a system level service:
```shell
sudo systemctl enable --now coder
```
The following command will get you information about the Coder launch service
```shell
journalctl -u coder.service -b
```
This will return a series of logs related to running Coder as a system service.
Embedded in the logs is the Coder Access URL.
Copy the URL and run the following command to create the first user, either on
your local machine or in the instance terminal.
```shell
coder login <url***.try.coder.app>
```
Fill out the prompts. Be sure to save use email and password as these are your
admin username and password.
You can now access Coder on your local machine with the relevant
`***.try.coder.app` URL and logging in with the username and password.
## Creating and Uploading Your First Template
First, run `coder template init` to create your first template. You’ll be given
a list of possible templates to use. This tutorial will show you how to set up
your Coder instance to create a Linux based machine on Azure.
<img src="../../images/platforms/azure/azure9.png">
Press `enter` to select `Develop in Linux on Azure` template. This will return
the following:
<img src="../../images/platforms/azure/azure10.png">
To get started using the Azure template, install the Azure CLI by following the
instructions
[here](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli-linux?pivots=apt).
Run `az login` and follow the instructions to configure the Azure command line.
Coder is running as a system service, which creates the system user `coder` for
handling processes. The Coder user will require access to the Azure credentials
to initialize the template.
Run the following commands to copy the Azure credentials and give the `coder`
user access to them:
```shell
sudo cp -r ~/.azure /home/coder/.azure
sudo chown -R coder:coder /home/coder/.azure/
```
Navigate to the `./azure-linux` folder where you created your template and run
the following command to put the template on your Coder instance.
```shell
coder templates push
```
Congrats! You can now navigate to your Coder dashboard and use this Linux on
Azure template to create a new workspace!
docs/install/cloud/compute-engine.md
+78
View File
@@ -0,0 +1,78 @@
# Google Cloud Platform
In this guide, you will learn how to deploy the Coder control plane instance and
your first template.
## Requirements
This guide assumes you have `roles/compute.instanceAdmin.v1` access to your
Google Cloud Platform project.
## Launch a Coder instance from the Google Cloud Marketplace
We publish an Ubuntu 22.04 VM image with Coder and Docker pre-installed. Search
for `Coder v2` in the GCP Marketplace or
[use direct link](https://console.cloud.google.com/marketplace/product/coder-enterprise-market-public/coder-v2).
![Coder on GCP Marketplace](../../images/platforms/gcp/marketplace.png)
Be sure to keep the default firewall options checked so you can connect over
HTTP, HTTPS, and SSH.
We recommend keeping the default instance type (`e2-standard-4`, 4 cores and 16
GB memory) if you plan on provisioning Docker containers as workspaces on this
VM instance. Keep in mind this platforms is intended for proof-of-concept
deployments and you should adjust your infrastructure when preparing for
production use. See: [Scaling Coder](../../admin/infrastructure/index.md)
<video autoplay playsinline loop>
<source src="https://github.com/coder/coder/blob/main/docs/images/platforms/gcp/launch.mp4?raw=true" type="video/mp4">
Your browser does not support the video tag.
</video>
Be sure to add a keypair so that you can connect over SSH to further
[configure Coder](../../admin/setup/index.md).
After launching the instance, wait 30 seconds and navigate to the public IPv4
address. You should be redirected to a public tunnel URL.
![Coder on GCP Marketplace start](../../images/platforms/gcp/start.png)
That's all! Use the UI to create your first user, template, and workspace. We
recommend starting with a Docker template since the instance has Docker
pre-installed.
![Coder Workspace and IDE in GCP VM](../../images/platforms/aws/workspace.png)
## Configuring Coder server
Coder is primarily configured by server-side flags and environment variables.
Given you created or added key-pairs when launching the instance, you can
[configure your Coder deployment](../../admin/setup/index.md) by logging in via
SSH or using the console:
```shell
ssh ubuntu@<gcp-public-IPv4>
sudo vim /etc/coder.d/coder.env # edit config
sudo systemctl daemon-reload
sudo systemctl restart coder # restart Coder
```
## Give developers VM workspaces (optional)
Instead of running containers on the Coder instance, you can offer developers
full VM instances with the
[gcp-linux](https://github.com/coder/coder/tree/main/examples/templates/gcp-linux)
template.
Before you can use this template, you must authorize Coder to create VM
instances in your GCP project. Follow the instructions in the
[gcp-linux template README](https://github.com/coder/coder/tree/main/examples/templates/gcp-linux#authentication)
to set up authentication.
### Next Steps
- [Use your IDE with Coder](../../user-guides/workspace-access/index.md)
- [Writing custom templates for Coder](../../admin/templates/index.md)
- [Configure the Coder server](../../admin/setup/index.md)
- [Use your own domain + TLS](../../admin/setup/index.md#tls--reverse-proxy)
docs/install/cloud/ec2.md
+90
View File
@@ -0,0 +1,90 @@
# Amazon Web Services
This guide is designed to get you up and running with a Coder proof-of-concept
VM on AWS EC2 using a [Coder-provided AMI](https://github.com/coder/packages).
If you are familiar with EC2 however, you can use our
[install script](../cli.md) to run Coder on any popular Linux distribution.
## Requirements
This guide assumes your AWS account has `AmazonEC2FullAccess` permissions.
## Launch a Coder instance from the from AWS Marketplace
We publish an Ubuntu 22.04 AMI with Coder and Docker pre-installed. Search for
`Coder` in the EC2 "Launch an Instance" screen or
[launch directly from the marketplace](https://aws.amazon.com/marketplace/pp/prodview-5gxjyur2vc7rg).
![Coder on AWS Marketplace](../../images/platforms/aws/marketplace.png)
Be sure to keep the default firewall (SecurityGroup) options checked so you can
connect over HTTP, HTTPS, and SSH.
![AWS Security Groups](../../images/platforms/aws/security-groups.png)
We recommend keeping the default instance type (`t2.xlarge`, 4 cores and 16 GB
memory) if you plan on provisioning Docker containers as workspaces on this EC2
instance. Keep in mind this platforms is intended for proof-of-concept
deployments and you should adjust your infrastructure when preparing for
production use. See: [Scaling Coder](../../admin/infrastructure/index.md)
Be sure to add a keypair so that you can connect over SSH to further
[configure Coder](../../admin/setup/index.md).
After launching the instance, wait 30 seconds and navigate to the public IPv4
address. You should be redirected to a public tunnel URL.
<video autoplay playsinline loop>
<source src="https://github.com/coder/coder/blob/main/docs/images/platforms/aws/launch.mp4?raw=true" type="video/mp4">
Your browser does not support the video tag.
</video>
That's all! Use the UI to create your first user, template, and workspace. We
recommend starting with a Docker template since the instance has Docker
pre-installed.
![Coder Workspace and IDE in AWS EC2](../../images/platforms/aws/workspace.png)
## Configuring Coder server
Coder is primarily configured by server-side flags and environment variables.
Given you created or added key-pairs when launching the instance, you can
[configure your Coder deployment](../../admin/setup/index.md) by logging in via
SSH or using the console:
<!-- TOOD(@kylecarbs): fix this weird formatting (https://imgur.com/a/LAUY3cT) -->
```sh
ssh ubuntu@<ec2-public-IPv4>
sudo vim /etc/coder.d/coder.env # edit config
sudo systemctl daemon-reload
sudo systemctl restart coder # restart Coder
```
## Give developers EC2 workspaces (optional)
Instead of running containers on the Coder instance, you can offer developers
full EC2 instances with the
[aws-linux](https://github.com/coder/coder/tree/main/examples/templates/aws-linux)
template.
Before you add the AWS template from the dashboard or CLI, you'll need to modify
the instance IAM role.
![Modify IAM role](../../images/platforms/aws/modify-iam.png)
You must create or select a role that has `EC2FullAccess` permissions or a
limited
[Coder-specific permissions policy](https://github.com/coder/coder/tree/main/examples/templates/aws-linux#required-permissions--policy).
From there, you can import the AWS starter template in the dashboard and begin
creating VM-based workspaces.
![Modify IAM role](../../images/platforms/aws/aws-linux.png)
## Next steps
- [IDEs with Coder](../../user-guides/workspace-access/index.md)
- [Writing custom templates for Coder](../../admin/templates/index.md)
- [Configure the Coder server](../../admin/setup/index.md)
- [Use your own domain + TLS](../../admin/setup/index.md#tls--reverse-proxy)
docs/install/cloud/index.md
+44
View File
@@ -0,0 +1,44 @@
# Cloud Platforms
We provide install guides and example templates for deploying Coder to your
cloud of choice.
<div class="tabs">
## AWS
We publish an EC2 image with Coder pre-installed. Follow the tutorial here:
- [Install Coder on AWS EC2](./ec2.md)
Alternatively, install the [CLI binary](../cli.md) on any Linux machine or
follow our [Kubernetes](../kubernetes.md) documentation to install Coder on an
existing EKS cluster.
## GCP
We publish a GCP Marketplace listing with Coder pre-installed. Follow the
tutorial here:
- [Install Coder on GCP Compute Engine](./compute-engine.md)
Alternatively, install the [CLI binary](../cli.md) on any Linux machine or
follow our [Kubernetes](../kubernetes.md) documentation to install Coder on an
existing GKE cluster.
## Azure
Use the following guide to run Coder on an Azure VM:
- [Install Coder on an Azure VM](./azure-vm.md)
Alternatively, install the [CLI binary](../cli.md) on any Linux machine or
follow our [Kubernetes](../kubernetes.md) documentation to install Coder on an
existing GKE cluster.
## Other
Is your cloud missing? Check [unofficial](../other/index.md) install methods or
install the [standalone binary](../cli.md).
</div>
docs/install/database.md
-95
View File
@@ -1,95 +0,0 @@
## Recommendation
For production deployments, we recommend using an external
[PostgreSQL](https://www.postgresql.org/) database (version 13 or higher).
## Basic configuration
Before starting the Coder server, prepare the database server by creating a role
and a database. Remember that the role must have access to the created database.
With `psql`:
```sql
CREATE ROLE coder LOGIN SUPERUSER PASSWORD 'secret42';
```
With `psql -U coder`:
```sql
CREATE DATABASE coder;
```
Coder configuration is defined via
[environment variables](../admin/configure.md). The database client requires the
connection string provided via the `CODER_PG_CONNECTION_URL` variable.
```shell
export CODER_PG_CONNECTION_URL="postgres://coder:secret42@localhost/coder?sslmode=disable"
```
## Custom schema
For installations with elevated security requirements, it's advised to use a
separate [schema](https://www.postgresql.org/docs/current/ddl-schemas.html)
instead of the public one.
With `psql -U coder`:
```sql
CREATE SCHEMA myschema;
```
Once the schema is created, you can list all schemas with `\dn`:
```
List of schemas
Name | Owner
-----------+----------
myschema | coder
public | postgres
(2 rows)
```
In this case the database client requires the modified connection string:
```shell
export CODER_PG_CONNECTION_URL="postgres://coder:secret42@localhost/coder?sslmode=disable&search_path=myschema"
```
The `search_path` parameter determines the order of schemas in which they are
visited while looking for a specific table. The first schema named in the search
path is called the current schema. By default `search_path` defines the
following schemas:
```sql
SHOW search_path;
search_path
--------------
"$user", public
```
Using the `search_path` in the connection string corresponds to the following
`psql` command:
```sql
ALTER ROLE coder SET search_path = myschema;
```
## Troubleshooting
### Coder server fails startup with "current_schema: converting NULL to string is unsupported"
Please make sure that the schema selected in the connection string
`...&search_path=myschema` exists and the role has granted permissions to access
it. The schema should be present on this listing:
```shell
psql -U coder -c '\dn'
```
## Next steps
- [Configuring Coder](../admin/configure.md)
- [Templates](../templates/index.md)
docs/install/docker.md
+32 -32
View File
@@ -1,19 +1,21 @@
# Install Coder via Docker
You can install and run Coder using the official Docker images published on
[GitHub Container Registry](https://github.com/coder/coder/pkgs/container/coder).
## Requirements
Docker is required. See the
[official installation documentation](https://docs.docker.com/install/).
- Docker. See the
[official installation documentation](https://docs.docker.com/install/).
> Note that the below steps are only supported on a Linux distribution. If on
> macOS, please [run Coder via the standalone binary](./index.md#manual).
- A Linux machine. For macOS devices, start Coder using the
[standalone binary](./cli.md).
<div class="tabs">
- 2 CPU cores and 4 GB memory free on your machine.
## docker run
## Install Coder via `docker run`
**Built-in database (quick)**
### Built-in database (quick)
For proof-of-concept deployments, you can run a complete Coder instance with the
following command.
@@ -29,7 +31,7 @@ docker run --rm -it \
ghcr.io/coder/coder:latest
```
**External database**
### External database (recommended)
For production deployments, we recommend using an external PostgreSQL database
(version 13 or higher). Set `CODER_ACCESS_URL` to the external URL that users
@@ -45,7 +47,7 @@ docker run --rm -it \
ghcr.io/coder/coder:latest
```
## docker compose
## Install Coder via `docker compose`
Coder's publishes a
[docker-compose example](https://github.com/coder/coder/blob/main/docker-compose.yaml)
@@ -67,45 +69,43 @@ which includes an PostgreSQL container and volume.
4. Start Coder with `docker compose up`
5. Visit the web ui via the configured url.
5. Visit the web UI via the configured url.
6. Follow the on-screen instructions log in and create your first template and
workspace
</div>
Coder configuration is defined via environment variables. Learn more about
Coder's [configuration options](../admin/configure.md).
> **Note:** In order to use cloud-based templates (e.g. Kubernetes, AWS), you
> must have an external URL that users and workspaces will use to connect to
> Coder.
>
> > For proof-of-concept deployments, you can use
> > [Coder's tunnel](../admin/configure.md#tunnel).
> >
> > For production deployments, we recommend setting an
> > [access URL](../admin/configure.md#access-url)
> **Note:** Coder runs as a non-root user, we use `--group-add` to ensure Coder
> has permissions to manage Docker via `docker.sock`. If the host systems
> `/var/run/docker.sock` is not group writeable or does not belong to the
> `docker` group, the above may not work as-is.
Coder's [configuration options](../admin/setup/index.md).
## Troubleshooting
### Docker-based workspace is stuck in "Connecting..."
Ensure you have an externally-reachable `CODER_ACCESS_URL` set. See
[troubleshooting templates](../templates/index.md#troubleshooting-templates) for
more steps.
[troubleshooting templates](../admin/templates/troubleshooting.md) for more
steps.
### Permission denied while trying to connect to the Docker daemon socket
See Docker's official documentation to
[Manage Docker as a non-root user](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user)
### I cannot add Docker templates
Coder runs as a non-root user, we use `--group-add` to ensure Coder has
permissions to manage Docker via `docker.sock`. If the host systems
`/var/run/docker.sock` is not group writeable or does not belong to the `docker`
group, the above may not work as-is.
### I cannot add cloud-based templates
In order to use cloud-based templates (e.g. Kubernetes, AWS), you must have an
external URL that users and workspaces will use to connect to Coder. For
proof-of-concept deployments, you can use
[Coder's tunnel](../admin/setup/index.md#tunnel). For production deployments, we
recommend setting an [access URL](../admin/setup/index.md#access-url)
## Next steps
- [Configuring Coder](../admin/configure.md)
- [Templates](../templates/index.md)
- [Create your first template](../tutorials/template-from-scratch.md)
- [Control plane configuration](../admin/setup/index.md#configure-control-plane-access)
docs/install/index.md
+2 -1
View File
@@ -64,4 +64,5 @@ coder login https://coder.example.com
## Next up
- [Create your first template](../templates/tutorial.md)
- [Create your first template](../start/first-template.md)
- [Expose your control plane to other users](../admin/setup/index.md)
docs/install/kubernetes.md
+123 -128
View File
@@ -1,164 +1,159 @@
# Install Coder on Kubernetes
You can install Coder on Kubernetes using Helm. We run on most Kubernetes
distributions, including [OpenShift](./other/openshift.md).
## Requirements
Before proceeding, please ensure that you have a Kubernetes cluster running K8s
1.19+ and have Helm 3.5+ installed.
- Kubernetes cluster running K8s 1.19+
- [Helm](https://helm.sh/docs/intro/install/) 3.5+ installed on your local
machine
You'll also want to install the
[latest version of Coder](https://github.com/coder/coder/releases/latest)
locally in order to log in and manage templates.
## 1. Create a namespace
> Coder supports two release channels: mainline for the true latest version of
> Coder, and stable for large enterprise deployments. Before installing your
> control plane via Helm, please read the [Releases](./releases.md) document to
> identify the best-suited release for your team, then specify the version using
> Helm's `--version` flag.
Create a namespace for the Coder control plane. In this tutorial, we'll call it
`coder`.
> The version flags for both stable and mainline are automatically filled in
> this page.
```sh
kubectl create namespace coder
```
> If you need help setting up k8s, we have a
> [repo with Terraform configuration](https://github.com/ElliotG/coder-oss-tf)
> to provision Coder on Google GKE, Azure AKS, AWS EKS, DigitalOcean DOKS,
> IBMCloud K8s, OVHCloud K8s, and Scaleway K8s Kapsule.
## 2. Create a PostgreSQL instance
## Install Coder with Helm
Coder does not manage a database server for you. This is required for storing
data about your Coder deployment and resources.
1. Create a namespace for Coder, such as `coder`:
### Managed PostgreSQL (recommended)
```console
kubectl create namespace coder
```
If you're in a public cloud such as
[Google Cloud](https://cloud.google.com/sql/docs/postgres/),
[AWS](https://aws.amazon.com/rds/postgresql/),
[Azure](https://docs.microsoft.com/en-us/azure/postgresql/), or
[DigitalOcean](https://www.digitalocean.com/products/managed-databases-postgresql),
you can use the managed PostgreSQL offerings they provide. Make sure that the
PostgreSQL service is running and accessible from your cluster. It should be in
the same network, same project, etc.
1. Create a PostgreSQL deployment. Coder does not manage a database server for
you.
### In-Cluster PostgreSQL (for proof of concepts)
If you're in a public cloud such as
[Google Cloud](https://cloud.google.com/sql/docs/postgres/),
[AWS](https://aws.amazon.com/rds/postgresql/),
[Azure](https://docs.microsoft.com/en-us/azure/postgresql/), or
[DigitalOcean](https://www.digitalocean.com/products/managed-databases-postgresql),
you can use the managed PostgreSQL offerings they provide. Make sure that the
PostgreSQL service is running and accessible from your cluster. It should be
in the same network, same project, etc.
You can install Postgres manually on your cluster using the
[Bitnami PostgreSQL Helm chart](https://github.com/bitnami/charts/tree/master/bitnami/postgresql#readme).
There are some [helpful guides](https://phoenixnap.com/kb/postgresql-kubernetes)
on the internet that explain sensible configurations for this chart. Example:
You can install Postgres manually on your cluster using the
[Bitnami PostgreSQL Helm chart](https://github.com/bitnami/charts/tree/master/bitnami/postgresql#readme).
There are some
[helpful guides](https://phoenixnap.com/kb/postgresql-kubernetes) on the
internet that explain sensible configurations for this chart. Example:
```console
# Install PostgreSQL
helm repo add bitnami https://charts.bitnami.com/bitnami
helm install coder-db bitnami/postgresql \
--namespace coder \
--set auth.username=coder \
--set auth.password=coder \
--set auth.database=coder \
--set persistence.size=10Gi
```
```console
# Install PostgreSQL
helm repo add bitnami https://charts.bitnami.com/bitnami
helm install coder-db bitnami/postgresql \
--namespace coder \
--set auth.username=coder \
--set auth.password=coder \
--set auth.database=coder \
--set persistence.size=10Gi
```
The cluster-internal DB URL for the above database is:
The cluster-internal DB URL for the above database is:
```shell
postgres://coder:coder@coder-db-postgresql.coder.svc.cluster.local:5432/coder?sslmode=disable
```
```shell
postgres://coder:coder@coder-db-postgresql.coder.svc.cluster.local:5432/coder?sslmode=disable
```
You can optionally use the
[Postgres operator](https://github.com/zalando/postgres-operator) to manage
PostgreSQL deployments on your Kubernetes cluster.
> Ensure you set up periodic backups so you don't lose data.
## 3. Create the PostgreSQL secret
You can use [Postgres operator](https://github.com/zalando/postgres-operator)
to manage PostgreSQL deployments on your Kubernetes cluster.
Create a secret with the PostgreSQL database URL string. In the case of the
self-managed PostgreSQL, the address will be:
1. Create a secret with the database URL:
```sh
kubectl create secret generic coder-db-url -n coder \
--from-literal=url="postgres://coder:coder@coder-db-postgresql.coder.svc.cluster.local:5432/coder?sslmode=disable"
```
```shell
# Uses Bitnami PostgreSQL example. If you have another database,
# change to the proper URL.
kubectl create secret generic coder-db-url -n coder \
--from-literal=url="postgres://coder:coder@coder-db-postgresql.coder.svc.cluster.local:5432/coder?sslmode=disable"
```
## 4. Install Coder with Helm
1. Add the Coder Helm repo:
```shell
helm repo add coder-v2 https://helm.coder.com/v2
```
```shell
helm repo add coder-v2 https://helm.coder.com/v2
```
Create a `values.yaml` with the configuration settings you'd like for your
deployment. For example:
1. Create a `values.yaml` with the configuration settings you'd like for your
deployment. For example:
```yaml
coder:
# You can specify any environment variables you'd like to pass to Coder
# here. Coder consumes environment variables listed in
# `coder server --help`, and these environment variables are also passed
# to the workspace provisioner (so you can consume them in your Terraform
# templates for auth keys etc.).
#
# Please keep in mind that you should not set `CODER_HTTP_ADDRESS`,
# `CODER_TLS_ENABLE`, `CODER_TLS_CERT_FILE` or `CODER_TLS_KEY_FILE` as
# they are already set by the Helm chart and will cause conflicts.
env:
- name: CODER_PG_CONNECTION_URL
valueFrom:
secretKeyRef:
# You'll need to create a secret called coder-db-url with your
# Postgres connection URL like:
# postgres://coder:password@postgres:5432/coder?sslmode=disable
name: coder-db-url
key: url
```yaml
coder:
# You can specify any environment variables you'd like to pass to Coder
# here. Coder consumes environment variables listed in
# `coder server --help`, and these environment variables are also passed
# to the workspace provisioner (so you can consume them in your Terraform
# templates for auth keys etc.).
#
# Please keep in mind that you should not set `CODER_HTTP_ADDRESS`,
# `CODER_TLS_ENABLE`, `CODER_TLS_CERT_FILE` or `CODER_TLS_KEY_FILE` as
# they are already set by the Helm chart and will cause conflicts.
env:
- name: CODER_PG_CONNECTION_URL
valueFrom:
secretKeyRef:
# You'll need to create a secret called coder-db-url with your
# Postgres connection URL like:
# postgres://coder:password@postgres:5432/coder?sslmode=disable
name: coder-db-url
key: url
# (Optional) For production deployments the access URL should be set.
# If you're just trying Coder, access the dashboard via the service IP.
- name: CODER_ACCESS_URL
value: "https://coder.example.com"
# (Optional) For production deployments the access URL should be set.
# If you're just trying Coder, access the dashboard via the service IP.
- name: CODER_ACCESS_URL
value: "https://coder.example.com"
#tls:
# secretNames:
# - my-tls-secret-name
```
#tls:
# secretNames:
# - my-tls-secret-name
```
> You can view our
> [Helm README](https://github.com/coder/coder/blob/main/helm#readme) for
> details on the values that are available, or you can view the
> [values.yaml](https://github.com/coder/coder/blob/main/helm/coder/values.yaml)
> file directly.
> You can view our
> [Helm README](https://github.com/coder/coder/blob/main/helm#readme) for
> details on the values that are available, or you can view the
> [values.yaml](https://github.com/coder/coder/blob/main/helm/coder/values.yaml)
> file directly.
We support two release channels: mainline and stable - read the
[Releases](./releases.md) page to learn more about which best suits your team.
1. Run the following command to install the chart in your cluster.
For the **mainline** Coder release:
For the **mainline** Coder release:
<!-- autoversion(mainline): "--version [version]" -->
```shell
helm install coder coder-v2/coder \
--namespace coder \
--values values.yaml \
--version 2.16.0
```
```shell
helm install coder coder-v2/coder \
--namespace coder \
--values values.yaml \
--version 2.15.0
```
For the **stable** Coder release:
For the **stable** Coder release:
<!-- autoversion(stable): "--version [version]" -->
<!-- autoversion(stable): "--version [version]" -->
```shell
helm install coder coder-v2/coder \
--namespace coder \
--values values.yaml \
--version 2.15.1
```
```shell
helm install coder coder-v2/coder \
--namespace coder \
--values values.yaml \
--version 2.15.1
```
You can watch Coder start up by running `kubectl get pods -n coder`. Once
Coder has started, the `coder-*` pods should enter the `Running` state.
You can watch Coder start up by running `kubectl get pods -n coder`. Once Coder
has started, the `coder-*` pods should enter the `Running` state.
1. Log in to Coder
## 5. Log in to Coder 🎉
Use `kubectl get svc -n coder` to get the IP address of the LoadBalancer.
Visit this in the browser to set up your first account.
Use `kubectl get svc -n coder` to get the IP address of the LoadBalancer. Visit
this in the browser to set up your first account.
If you do not have a domain, you should set `CODER_ACCESS_URL` to this URL in
the Helm chart and upgrade Coder (see below). This allows workspaces to
connect to the proper Coder URL.
If you do not have a domain, you should set `CODER_ACCESS_URL` to this URL in
the Helm chart and upgrade Coder (see below). This allows workspaces to connect
to the proper Coder URL.
## Upgrading Coder via Helm
@@ -292,10 +287,10 @@ Ensure you have an externally-reachable `CODER_ACCESS_URL` set in your helm
chart. If you do not have a domain set up, this should be the IP address of
Coder's LoadBalancer (`kubectl get svc -n coder`).
See [troubleshooting templates](../templates/index.md#troubleshooting-templates)
for more steps.
See [troubleshooting templates](../admin/templates/troubleshooting.md) for more
steps.
## Next steps
- [Configuring Coder](../admin/configure.md)
- [Templates](../templates/index.md)
- [Create your first template](../tutorials/template-from-scratch.md)
- [Control plane configuration](../admin/setup/index.md)
docs/install/offline.md
+18 -13
View File
@@ -6,15 +6,15 @@ environments. However, some changes to your configuration are necessary.
> This is a general comparison. Keep reading for a full tutorial running Coder
> offline with Kubernetes or Docker.
| | Public deployments | Offline deployments |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Terraform binary | By default, Coder downloads Terraform binary from [releases.hashicorp.com](https://releases.hashicorp.com) | Terraform binary must be included in `PATH` for the VM or container image. [Supported versions](https://github.com/coder/coder/blob/main/provisioner/terraform/install.go#L23-L24) |
| Terraform registry | Coder templates will attempt to download providers from [registry.terraform.io](https://registry.terraform.io) or [custom source addresses](https://developer.hashicorp.com/terraform/language/providers/requirements#source-addresses) specified in each template | [Custom source addresses](https://developer.hashicorp.com/terraform/language/providers/requirements#source-addresses) can be specified in each Coder template, or a custom registry/mirror can be used. More details below |
| STUN | By default, Coder uses Google's public STUN server for direct workspace connections | STUN can be safely [disabled](../reference/ users can still connect via [relayed connections](../networking/index.md#-geo-distribution). Alternatively, you can set a [custom DERP server](../reference/cli/server.md#--derp-server-stun-addresses) |
| DERP | By default, Coder's built-in DERP relay can be used, or [Tailscale's public relays](../networking/index.md#relayed-connections). | By default, Coder's built-in DERP relay can be used, or [custom relays](../networking/index.md#custom-relays). |
| PostgreSQL | If no [PostgreSQL connection URL](../reference/cli/server.md#--postgres-url) is specified, Coder will download Postgres from [repo1.maven.org](https://repo1.maven.org) | An external database is required, you must specify a [PostgreSQL connection URL](../reference/cli/server.md#--postgres-url) |
| Telemetry | Telemetry is on by default, and [can be disabled](../reference/cli/server.md#--telemetry) | Telemetry [can be disabled](../reference/cli/server.md#--telemetry) |
| Update check | By default, Coder checks for updates from [GitHub releases](https:/github.com/coder/coder/releases) | Update checks [can be disabled](../reference/cli/server.md#--update-check) |
| | Public deployments | Offline deployments |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Terraform binary | By default, Coder downloads Terraform binary from [releases.hashicorp.com](https://releases.hashicorp.com) | Terraform binary must be included in `PATH` for the VM or container image. [Supported versions](https://github.com/coder/coder/blob/main/provisioner/terraform/install.go#L23-L24) |
| Terraform registry | Coder templates will attempt to download providers from [registry.terraform.io](https://registry.terraform.io) or [custom source addresses](https://developer.hashicorp.com/terraform/language/providers/requirements#source-addresses) specified in each template | [Custom source addresses](https://developer.hashicorp.com/terraform/language/providers/requirements#source-addresses) can be specified in each Coder template, or a custom registry/mirror can be used. More details below |
| STUN | By default, Coder uses Google's public STUN server for direct workspace connections | STUN can be safely [disabled](../reference/ users can still connect via [relayed connections](../admin/networking/index.md#-geo-distribution). Alternatively, you can set a [custom DERP server](../reference/cli/server.md#--derp-server-stun-addresses) |
| DERP | By default, Coder's built-in DERP relay can be used, or [Tailscale's public relays](../admin/networking/index.md#relayed-connections). | By default, Coder's built-in DERP relay can be used, or [custom relays](../admin/networking/index.md#custom-relays). |
| PostgreSQL | If no [PostgreSQL connection URL](../reference/cli/server.md#--postgres-url) is specified, Coder will download Postgres from [repo1.maven.org](https://repo1.maven.org) | An external database is required, you must specify a [PostgreSQL connection URL](../reference/cli/server.md#--postgres-url) |
| Telemetry | Telemetry is on by default, and [can be disabled](../reference/cli/server.md#--telemetry) | Telemetry [can be disabled](../reference/cli/server.md#--telemetry) |
| Update check | By default, Coder checks for updates from [GitHub releases](https:/github.com/coder/coder/releases) | Update checks [can be disabled](../reference/cli/server.md#--update-check) |
## Offline container images
@@ -117,7 +117,7 @@ ENV TF_CLI_CONFIG_FILE=/home/coder/.terraformrc
> [example templates](https://github.com/coder/coder/tree/main/examples/templates)
> you intend to use.
```hcl
```tf
# filesystem-mirror-example.tfrc
provider_installation {
filesystem_mirror {
@@ -126,7 +126,7 @@ provider_installation {
}
```
```hcl
```tf
# network-mirror-example.tfrc
provider_installation {
network_mirror {
@@ -233,7 +233,7 @@ accessible for your team to use.
## Coder Modules
To use Coder modules in offline installations please follow the instructions
[here](../templates/modules.md#offline-installations).
[here](../admin/templates/extending-templates/modules.md#offline-installations).
## Firewall exceptions
@@ -249,7 +249,7 @@ Coder is installed.
## JetBrains IDEs
Gateway, JetBrains' remote development product that works with Coder,
[has documented offline deployment steps.](../ides/gateway.md#jetbrains-gateway-in-an-offline-environment)
[has documented offline deployment steps.](../user-guides/workspace-access/jetbrains.md#jetbrains-gateway-in-an-offline-environment)
## Microsoft VS Code Remote - SSH
@@ -261,3 +261,8 @@ local machine has outbound HTTPS (port 443) connectivity to:
- update.code.visualstudio.com
- vscode.blob.core.windows.net
- \*.vo.msecnd.net
## Next steps
- [Create your first template](../tutorials/template-from-scratch.md)
- [Control plane configuration](../admin/setup/index.md)
docs/install/openshift.md
+9 -8
View File
@@ -1,13 +1,9 @@
## Requirements
Before proceeding, please ensure that you have an OpenShift cluster running K8s
1.19+ (OpenShift 4.7+) and have Helm 3.5+ installed. In addition, you'll need to
install the OpenShift CLI (`oc`) to authenticate to your cluster and create
OpenShift resources.
You'll also want to install the
[latest version of Coder](https://github.com/coder/coder/releases/latest)
locally in order to log in and manage templates.
- OpenShift cluster running K8s 1.19+ (OpenShift 4.7+)
- Helm 3.5+ installed
- OpenShift CLI (`oc`) installed
- [Coder CLI](./cli.md) installed
## Install Coder with OpenShift
@@ -326,3 +322,8 @@ coder template push kubernetes -d .
```
This template should be ready to use straight away.
## Next steps
- [Create your first template](../tutorials/template-from-scratch.md)
- [Control plane configuration](../admin/setup/index.md)
docs/install/other/index.md
+17
View File
@@ -0,0 +1,17 @@
# Alternate install methods
Coder has a number of alternate unofficial install methods. Contributions are
welcome!
| Platform Name | Status | Documentation |
| --------------------------------------------------------------------------------- | ---------- | -------------------------------------------------------------------------------------------- |
| AWS EC2 | Official | [Guide: AWS](../cloud/ec2.md) |
| Google Compute Engine | Official | [Guide: Google Compute Engine](../cloud/compute-engine.md) |
| Azure AKS | Unofficial | [GitHub: coder-aks](https://github.com/ericpaulsen/coder-aks) |
| Terraform (GKE, AKS, LKE, DOKS, IBMCloud K8s, OVHCloud K8s, Scaleway K8s Kapsule) | Unofficial | [GitHub: coder-oss-terraform](https://github.com/ElliotG/coder-oss-tf) |
| Fly.io | Unofficial | [Blog: Run Coder on Fly.io](https://coder.com/blog/remote-developer-environments-on-fly-io) |
| Garden.io | Unofficial | [GitHub: garden-coder-example](https://github.com/garden-io/garden-coder-example) |
| Railway.app | Unofficial | [Blog: Run Coder on Railway.app](https://coder.com/blog/deploy-coder-on-railway-app) |
| Heroku | Unofficial | [Docs: Deploy Coder on Heroku](https://github.com/coder/packages/blob/main/heroku/README.md) |
| Render | Unofficial | [Docs: Deploy Coder on Render](https://github.com/coder/packages/blob/main/render/README.md) |
| Snapcraft | Unofficial | [Get it from the Snap Store](https://snapcraft.io/coder) |
docs/install/other/openshift.md
View File
docs/install/releases.md
+4 -8
View File
@@ -7,10 +7,8 @@ We recommend enterprise customers test the compatibility of new releases with
their infrastructure on a staging environment before upgrading a production
deployment.
We support two release channels:
[mainline](https://github.com/coder/coder/releases/tag/v2.16.0) for the bleeding
edge version of Coder and
[stable](https://github.com/coder/coder/releases/latest) for those with lower
We support two release channels: [mainline](#mainline-releases) for the bleeding
edge version of Coder and [stable](#stable-releases) for those with lower
tolerance for fault. We field our mainline releases publicly for one month
before promoting them to stable.
@@ -47,12 +45,10 @@ pages.
## Release schedule
You can expect a release on the first Tuesday of every month excluding January.
We skip this release to allow ample time for our team members and customers to
return from the Holiday season.
| Release name | Release Date | Status |
| ------------ | ------------------ | ---------------- |
| 2.9.x | March 07, 2024 | Not Supported |
| 2.10.x | April 03, 2024 | Not Supported |
| 2.11.x | May 07, 2024 | Not Supported |
| 2.12.x | June 04, 2024 | Not Supported |
| 2.13.x | July 02, 2024 | Not Supported |
docs/install/upgrade.md
+55
View File
@@ -0,0 +1,55 @@
# Upgrade
This article walks you through how to upgrade your Coder server.
<blockquote class="danger">
<p>
Prior to upgrading a production Coder deployment, take a database snapshot since
Coder does not support rollbacks.
</p>
</blockquote>
To upgrade your Coder server, simply reinstall Coder using your original method
of [install](../install).
## Via install.sh
If you installed Coder using the `install.sh` script, re-run the below command
on the host:
```shell
curl -L https://coder.com/install.sh | sh
```
The script will unpack the new `coder` binary version over the one currently
installed. Next, you can restart Coder with the following commands (if running
it as a system service):
```shell
systemctl daemon-reload
systemctl restart coder
```
## Via docker-compose
If you installed using `docker-compose`, run the below command to upgrade the
Coder container:
```shell
docker-compose pull coder && docker-compose up -d coder
```
## Via Kubernetes
See
[Upgrading Coder via Helm](../install/kubernetes.md#upgrading-coder-via-helm).
## Via Windows
Download the latest Windows installer or binary from
[GitHub releases](https://github.com/coder/coder/releases/latest), or upgrade
from Winget.
```pwsh
winget install Coder.Coder
```