Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
136 changes: 65 additions & 71 deletions docs/install/index.md

Large diffs are not rendered by default.

4 changes: 3 additions & 1 deletion docs/install/plan/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,9 @@
---

Planning decides the shape of your deployment: which components run where, how large they need to be, and which choices are expensive to change later.
Work through this phase before you pick a platform in [Install the control plane](../server/index.md).
Planning is recommended, not required, before you install.
Work through this phase before you deploy Coder for other people to depend on, ideally before you pick a platform in [Install the control plane](../server/index.md).
For an evaluation, or when you've already chosen a platform, you can install the control plane first and come back to this phase.

## What you decide here

Expand All @@ -25,7 +27,7 @@

## Before you move on

You should be able to state, in a sentence each, where Coder will run, how many users it's sized for, and how users will reach it.

Check notice on line 30 in docs/install/plan/index.md

View workflow job for this annotation

GitHub Actions / lint-docs

Coder.AmbiguousWords

Use 'must, recommend' instead of 'should'; the word has more than one meaning. Refer to word-choice.md#choose-words-that-have-one-meaning.
If any of those are unclear, the answer usually lives in [Architecture](./architecture.md) or in the [Coder Validated Architecture](./sizing/index.md) reference designs.

Next: [Prepare prerequisites](../prepare/index.md).
Expand Down
1 change: 1 addition & 0 deletions docs/install/prepare/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ title: Prepare prerequisites
Preparation gathers the external pieces a deployment depends on.
Most of them are owned by another team, so their lead time, not the installation itself, usually sets your timeline.
Start the slowest items first.
For the CPU, memory, database, and platform versions the control plane itself needs, refer to [Installation requirements](../server/requirements.md).

## What to gather

Expand Down
7 changes: 6 additions & 1 deletion docs/install/server/cloud/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,11 @@ title: Cloud platforms

We provide install guides and example templates for deploying Coder to your cloud of choice.

If you already run a Kubernetes cluster in the cloud, follow [Install Coder on Kubernetes](../kubernetes/index.md) instead.
That guide covers managed clusters such as Amazon Elastic Kubernetes Service (EKS), Azure Kubernetes Service (AKS), and Google Kubernetes Engine (GKE).
Kubernetes is the recommended platform for deployments that others depend on.
The AWS Marketplace guide uses a CloudFormation template that creates a new EKS cluster for a proof of concept.

<div class="tabs">

## AWS
Expand Down Expand Up @@ -32,7 +37,7 @@ 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](https://coder.com/downloads) on any Linux machine or follow our [Kubernetes](../kubernetes/index.md) documentation to install Coder on an existing GKE cluster.
Alternatively, install the [CLI binary](https://coder.com/downloads) on any Linux machine or follow our [Kubernetes](../kubernetes/index.md) documentation to install Coder on an existing AKS cluster.

## Other

Expand Down
33 changes: 22 additions & 11 deletions docs/install/server/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,26 +4,37 @@

The pages in this section are alternatives, not sequential steps.
Choose the one that matches the platform your team already operates, or intends to operate, then follow it through to the end.
Before you start, check the [installation requirements](./requirements.md) for the platform you choose.

## Choose a platform

| Platform | Best suited to |
|-----------------------------------------------------|------------------------------------------------------------------------------|
| [Kubernetes](./kubernetes/index.md) | Production deployments, including high availability with multiple replicas |
| [Rancher](./rancher.md) | Kubernetes clusters your team already manages through Rancher |
| [OpenShift](./openshift.md) | Red Hat OpenShift clusters, which need specific security context settings |
| [Docker](./docker.md) | A single machine, such as a proof of concept or a small team deployment |
| [RPM for Red Hat Enterprise Linux (RHEL)](./rpm.md) | A single Red Hat Enterprise Linux host, or another RHEL-family distribution |
| [Cloud providers](./cloud/index.md) | A virtual machine on AWS, Google Cloud, or Azure, or a marketplace listing |
| [Community install methods](./community.md) | Platforms Coder doesn't package, where a community-contributed method exists |
| Where the control plane runs | Guide | Best suited to |
|------------------------------|-----------------------------------------------------|------------------------------------------------------------------------------|
| Kubernetes (recommended) | [Kubernetes](./kubernetes/index.md) | Production deployments, including high availability with multiple replicas |
| Kubernetes | [Rancher](./rancher.md) | Kubernetes clusters your team already manages through Rancher |
| Kubernetes | [OpenShift](./openshift.md) | Red Hat OpenShift clusters, which need specific security context settings |
| Container runtime | [Docker](./docker.md) | A single machine, such as a proof of concept or a small team deployment |
| Linux | [RPM for Red Hat Enterprise Linux (RHEL)](./rpm.md) | A single Red Hat Enterprise Linux host, or another RHEL-family distribution |
| Cloud platform | [Cloud providers](./cloud/index.md) | A virtual machine on AWS, Google Cloud, or Azure, or a marketplace listing |
| Other | [Community install methods](./community.md) | Platforms Coder doesn't package, where a community-contributed method exists |

If your platform choice is still open, size the deployment first in [Plan your deployment](../plan/index.md).
The [Coder Validated Architecture](../plan/sizing/index.md) reference designs assume Kubernetes, which is the recommended platform for deployments that others depend on.
Kubernetes is the recommended platform for deployments that others depend on, and the [Coder Validated Architecture](../plan/sizing/index.md) reference designs assume it.
The Kubernetes guide covers managed clusters such as Amazon Elastic Kubernetes Service (EKS), Azure Kubernetes Service (AKS), and Google Kubernetes Engine (GKE).
It also covers lightweight distributions such as K3s.
To install on a cluster you already run in the cloud, use the Kubernetes guide rather than [Cloud providers](./cloud/index.md).

## Deployments without internet access

If the deployment has no internet access, read [Air-gapped deployments](../prepare/airgap.md) before you install, and use it alongside the guide for your platform.
To try an air-gapped deployment from start to finish on one machine, follow [Install Coder on K3s in an air-gapped environment](./kubernetes/k3s-air-gapped.md).

If you need to size the deployment before you choose a platform, refer to [Plan your deployment](../plan/index.md).

## Before you move on

At the end of this phase you should be able to reach the Coder access URL, sign in as the first administrator, and see the deployment reported as healthy.

Check notice on line 35 in docs/install/server/index.md

View workflow job for this annotation

GitHub Actions / lint-docs

Coder.AmbiguousWords

Use 'must, recommend' instead of 'should'; the word has more than one meaning. Refer to word-choice.md#choose-words-that-have-one-meaning.
If you prepared a license and an identity provider application in [Prepare prerequisites](../prepare/index.md), apply them now so that the deployment you validate is the one you intend to run.
Then [create your first template](../../templates/creating-templates.md#from-a-starter-template) and build a workspace from it to confirm the deployment works end to end.

Next: [Validate your deployment](../validate/index.md).

Expand Down
6 changes: 5 additions & 1 deletion docs/install/server/kubernetes/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,11 @@
---

You can install Coder on Kubernetes (K8s) using Helm.
We run on most Kubernetes distributions, including [OpenShift](../openshift.md).
Coder runs on most Kubernetes distributions, including Amazon Elastic Kubernetes Service (EKS), Azure Kubernetes Service (AKS), Google Kubernetes Engine (GKE), K3s, and [OpenShift](../openshift.md).
Kubernetes is the recommended platform for deployments that others depend on.

If your cluster can't reach the internet, follow the [air-gapped installation guide](../../prepare/airgap.md) for the container image and Helm values.
To evaluate an offline installation on a single machine, follow [Install Coder on K3s in an air-gapped environment](./k3s-air-gapped.md).

## Requirements

Expand All @@ -28,7 +32,7 @@

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, and so on.

Check notice on line 35 in docs/install/server/kubernetes/index.md

View workflow job for this annotation

GitHub Actions / lint-docs

Coder.AmbiguousWords

Use 'must, recommend' instead of 'should'; the word has more than one meaning. Refer to word-choice.md#choose-words-that-have-one-meaning.

### In-Cluster PostgreSQL (for proof of concepts)

Expand Down Expand Up @@ -162,14 +166,14 @@
```

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.

Check notice on line 169 in docs/install/server/kubernetes/index.md

View workflow job for this annotation

GitHub Actions / lint-docs

Coder.AmbiguousWords

Use 'must, recommend' instead of 'should'; the word has more than one meaning. Refer to word-choice.md#choose-words-that-have-one-meaning.

## 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.

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).

Check notice on line 176 in docs/install/server/kubernetes/index.md

View workflow job for this annotation

GitHub Actions / lint-docs

Coder.AmbiguousWords

Use 'must, recommend' instead of 'should'; the word has more than one meaning. Refer to word-choice.md#choose-words-that-have-one-meaning.
This allows workspaces to connect to the proper Coder URL.

## Upgrade Coder via Helm
Expand Down Expand Up @@ -200,7 +204,7 @@
## Kubernetes Security Reference

Below are common requirements we see from our enterprise customers when deploying an application in Kubernetes.
This is intended to serve as a reference, and not all security requirements may apply to your business.

Check notice on line 207 in docs/install/server/kubernetes/index.md

View workflow job for this annotation

GitHub Actions / lint-docs

Coder.AmbiguousWords

Use 'might, can' instead of 'may'; the word has more than one meaning. Refer to word-choice.md#choose-words-that-have-one-meaning.

1. **All container images must be sourced from an internal container registry.**

Expand Down Expand Up @@ -288,8 +292,8 @@

### Kubernetes-based workspace is stuck in "Connecting..."

Ensure you have an externally-reachable `CODER_ACCESS_URL` set in your helm chart.

Check notice on line 295 in docs/install/server/kubernetes/index.md

View workflow job for this annotation

GitHub Actions / lint-docs

Coder.AmbiguousWords

Use 'make sure' instead of 'Ensure'; the word has more than one meaning. Refer to word-choice.md#choose-words-that-have-one-meaning.
If you do not have a domain set up, this should be the IP address of Coder's LoadBalancer (`kubectl get svc -n coder`).

Check notice on line 296 in docs/install/server/kubernetes/index.md

View workflow job for this annotation

GitHub Actions / lint-docs

Coder.AmbiguousWords

Use 'must, recommend' instead of 'should'; the word has more than one meaning. Refer to word-choice.md#choose-words-that-have-one-meaning.

See [troubleshooting templates](../../../templates/troubleshooting.md) for more steps.

Expand Down
69 changes: 69 additions & 0 deletions docs/install/server/requirements.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
---
title: Installation requirements
---

This page lists what a Coder deployment administrator needs before installing the Coder control plane.
Each guide in [Install the control plane](./index.md) repeats the requirements for its own platform.
For the items other teams usually provide, such as DNS records, certificates, and an identity provider application, refer to [Prepare prerequisites](../prepare/index.md).

## Control plane

| Resource | Requirement |
|------------------|-------------------------------------------------------------|
| CPU and memory | 2&nbsp;CPU cores and 4&nbsp;GiB of memory to evaluate Coder |
| Operating system | Linux, for every guide that Coder maintains in this section |
| Architecture | `amd64`, `arm64`, or `armv7` |

On Kubernetes, the Helm chart requests and limits the Coder container to 2&nbsp;CPU cores and 4&nbsp;GiB of memory unless you set `coder.resources` in your values file.
To try Coder on macOS or Windows, follow the [Quickstart](../../get-started/index.md) instead.

To size a production deployment, refer to the [Coder Validated Architecture](../plan/sizing/index.md).
Its reference architectures cover deployments of up to 1,000, 2,000, 3,000, and 10,000 users.

## Database

Coder stores its data in PostgreSQL 13 or later.

- On Kubernetes, you provide the database.
The [Kubernetes guide](./kubernetes/index.md#2-create-a-postgresql-instance) covers a managed PostgreSQL service and an in-cluster database for a proof of concept.
- The [Docker Compose example](./docker.md#install-coder-via-docker-compose) runs PostgreSQL in a container next to Coder.
- On a single host, `coder server` starts a built-in PostgreSQL database when `CODER_PG_CONNECTION_URL` isn't set.
The built-in database downloads PostgreSQL from the internet the first time it starts, so a deployment without internet access needs an external database.

For production, use an [external PostgreSQL database](./external-database.md) with a backup and restore plan.

## Platform

| Platform | Requirements |
|----------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------|
| [Kubernetes](./kubernetes/index.md) | Kubernetes 1.19 or later, and Helm 3.5 or later on the machine you install from |
| [Rancher](./rancher.md) | SUSE Rancher Manager 2.10 or later with the Rancher Prime distribution, a workload cluster that runs Kubernetes 1.19 or later, and Helm 3.5 or later |
| [OpenShift](./openshift.md) | OpenShift 4.7 or later, Helm 3.5 or later, the OpenShift CLI (`oc`), and the `coder` CLI |
| [Docker](./docker.md) | Docker on a Linux host |
| [Red Hat Enterprise Linux (RHEL) family](./rpm.md) | A [supported distribution](./rpm.md#supported-distributions) and `root` or `sudo` access |
| [Cloud platforms](./cloud/index.md) | The cloud account permissions that each guide lists |

## Network

- An [access URL](../../admin/setup/index.md#access-url): a hostname or IP address that both users and workspaces can reach.
- Without an access URL, `coder server` creates a public URL through a tunnel, which needs internet access.
- A [wildcard access URL](../../admin/setup/index.md#wildcard-access-url), such as `*.coder.example.com`, if you want to forward ports from the dashboard or serve workspace apps on subdomains.
The wildcard hostname needs a DNS record that resolves to Coder, and a TLS certificate that covers it.

## Internet access

All Coder features work without internet access.
A deployment without internet access needs the following:

- An external PostgreSQL database.
- A way to install the Terraform providers that your templates use.
- Templates that get their modules and tools from inside your network.

Refer to [Air-gapped deployments](../prepare/airgap.md).

## License

You can install Coder without a license.
Some features, including [AI Governance](../../ai-governance/index.md), need a Premium license.
Coder validates license keys locally, without an outbound connection, so a license also works in a deployment without internet access.
Refer to [Licensing](../prepare/licensing.md).
5 changes: 5 additions & 0 deletions docs/manifest.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

3 changes: 3 additions & 0 deletions docs/manifest/install/server.yml
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,9 @@ description: Choose a platform and install the Coder control plane on it.
path: ./install/server/index.md
icon_path: ./images/icons/download.svg
children:
- title: Requirements
description: Check the compute, database, platform, and network requirements for installing the Coder control plane.
path: ./install/server/requirements.md
- title: Docker
description: Install and run Coder using the official Docker images for a quick single-machine deployment.
path: ./install/server/docker.md
Expand Down
Loading