Files
coder/docs/install/index.md
T
coder[bot] d91aa1bebd docs: replace may with can or might per the Vale spike review (#31878)
Replaces `may` with `can` (ability or permission) or `might`
(possibility), following
`word-choice.md#choose-words-that-have-one-meaning`. The Vale findings
spike review marked every `may` row valid.

- 247 lines in 110 files: 75 became `can` and 162 became `might`. The
rest are small rewordings, such as "may wish" becoming "might want".
- Applied the reviewer notes:
- `.style/content-guidelines.md`: "docs may be written ahead" is now
"you can write docs ahead", which also drops the passive voice.
- `admin/external-auth.md`: now "You can grant access to a subset of
repositories.", so the sentence doesn't end on a preposition.
- Also fixed a typo in `gcp-to-aws.md`: "may needed" is now "might
need".

## Left as-is

- **`admin/setup/configuration-reference.md` (7 lines):** this page is
generated from `codersdk` deployment options (`<!-- DO NOT EDIT |
GENERATED CONTENT -->`), so the fix belongs in the Go option
descriptions, followed by `make gen`.
- **Text that quotes the product:**
- `admin/monitoring/health-check.md:196` matches the derphealth message.
- The heading at `templates/troubleshooting.md:45`, the first "may" on
line 47, and the link on line 67 match the web terminal's "your
workspace may be incomplete" warning and its anchor.
- `admin/integrations/oauth2-provider/troubleshooting.md:269` quotes a
server error.

The changed files have no new findings from other rules.

---
AI-generated by Superblink on behalf of @nickvigilante.

---------

Co-authored-by: coder[bot] <137810501+coder[bot]@users.noreply.github.com>
2026-11-06 17:17:35 -05:00

9.3 KiB

title
title
Install Coder in your infrastructure

This section covers how to install and run a Coder deployment, from the first decisions to a steady-state operating environment. You don't have to follow it from start to finish. Pick the path that matches what you're doing today, and use the rest of the section as a reference when you need it.

Choose your path

If you want to Start here What you skip
Try Coder on a single machine Quickstart Planning, prerequisites, and validation
Install on a platform you've already chosen Install the control plane Planning, unless you need to size the deployment
Deploy for a team, one step at a time The five phases, starting with phase 1 Nothing
Choose a platform or size a deployment Plan your deployment Installation steps
Upgrade a deployment that's already running Upgrading Everything except the upgrade guidance
Install only the coder command-line client Coder downloads page The rest of this section

Each phase page ends with a link to the next one, so you can also enter anywhere and keep reading in order.

Run Coder on a single server

The fastest way to run a Coder deployment is on one machine. The Quickstart installs Coder, starts it, and launches a first workspace in about 10 minutes. A single-server deployment fits an evaluation, a proof of concept, or a small team.

The Quickstart is quick because it skips most of the planning and prerequisites that a team deployment needs. Coder runs on one machine, so there's nothing to size. When CODER_ACCESS_URL isn't set, coder server opens a tunnel and gives you a try.coder.app URL, so you don't need DNS records or TLS certificates. You sign in with a password or with GitHub, so you don't set up an identity provider application, and you don't need a license.

Coder also uses its built-in PostgreSQL database unless you set CODER_PG_CONNECTION_URL. The built-in database lives on the same machine as Coder, so a deployment that people depend on needs a backup plan for that machine.

When you outgrow a single server, you don't need to start over. You can move the data to an external PostgreSQL database by following Migrate from the built-in database to an external database, then read Plan your deployment to decide how to grow.

The five phases

For a deployment others will rely on, work through the phases in order. Each phase produces the information the next one needs.

Phase What it answers What you finish with
1. Plan your deployment Which components run where, how large they need to be, who operates them A deployment shape and a size target you can hand to an infrastructure team
2. Prepare prerequisites What must exist before installation starts, and who owns each piece DNS, certificates, a database, a license, and an identity provider application
3. Install the control plane How to install Coder on the platform your team operates A running Coder deployment you can sign in to
4. Validate your deployment Whether the deployment is hardened, works, and holds up under load Evidence that the deployment is ready for real users
5. Operate and maintain How to keep the deployment healthy, upgraded, and correctly sized An upgrade and scaling routine, plus a removal path

Phases 1 and 2 are advisory rather than a gate. Nothing stops you from installing the control plane first, but the recommendations in those phases are what keep a deployment from needing to be rebuilt later.

Phase 1: Plan your deployment

Planning decides the topology, size, provisioning model, and network position of the deployment. It's the phase to read when you don't yet know what to install, or when more than one team has to agree on the answer. You finish with a deployment shape and a size target.

Skip it if you've already chosen a platform and you're deploying for a small number of users. Come back to it when the deployment grows, because topology, size, and network position are the decisions that are hardest to change after installation.

Phase 2: Prepare prerequisites

Preparation gathers what Coder depends on: a hostname and DNS records, TLS certificates, a PostgreSQL database, a license, and an identity provider application. Most of these belong to another team, so their lead time usually sets your timeline. Start the slowest requests early.

You can skip any item that doesn't apply to your deployment. A proof of concept can use the built-in database and skip the license and the identity provider application, so it needs little of this phase. A production deployment needs most of it.

Phase 3: Install the control plane

The pages in this phase are alternatives, not sequential steps. Choose the platform your team already operates, then follow that page to the end. You finish with a deployment you can reach and sign in to.

This is the one phase you can't skip. If you know your platform, you can start here and return to phases 1 and 2 for the details you need.

Phase 4: Validate your deployment

Validation hardens the deployment, then proves it works and holds up under load. It's how you find out whether the size target you chose in phase 1 was right.

Skip it for an evaluation. Do it before real users depend on the deployment.

Phase 5: Operate and maintain

Day-two operations cover upgrades, provisioning capacity, and removal. Read it after your deployment is running, and again before each upgrade.

Decisions worth making deliberately

Most choices in this section are easy to revisit. A few take real work to change after the fact, so it's worth making them on purpose:

  • Where the database runs. Moving from the built-in database to an external one is possible, but it means stopping Coder, dumping the database, and restoring it elsewhere. If you already know the deployment will serve a team, start with an external PostgreSQL database.
  • Topology, size, and network position. Changing how the control plane, database, and workspaces are laid out, or whether the deployment is public, private, or air-gapped, can mean rebuilding parts of it. Refer to Plan your deployment.

Who does the work

A Coder deployment usually crosses team boundaries. The following actors appear throughout this section, so you can anticipate which conversations you need to start and how long they're likely to take.

Actor Responsible for Appears in phase
Coder platform owner The deployment itself: installation, configuration, upgrades, and support 1 to 5
Infrastructure team Clusters, virtual machines, networking, load balancers, and egress rules 1 to 4
DNS and TLS owner The Coder hostname, the wildcard record for workspace apps, and certificates 2
Database administrator PostgreSQL provisioning, sizing, backups, and restore tests 2, 4, 5
Identity provider administrator The OpenID Connect (OIDC) application, claims, and group mappings 2
Security and compliance reviewer Audit requirements, network policy, data handling, and sign-off 2, 4
Licensing contact Purchasing and renewing the Coder license 2
Template author The workspace templates developers use once the deployment is running 4, 5

These are roles, not people. One person can serve as several actors, which is common for a proof of concept run by a single platform engineer. Several people can also serve as one actor, which is common for an infrastructure team that splits networking and compute ownership. Use the table to identify who has to agree, not to count headcount.