Skip to content
Coder Docs

Install Coder in your infrastructure

Plan, prepare, install, validate, and operate a Coder deployment in your own infrastructure.

On this page

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 toStart hereWhat you skip
Try Coder on a single machineQuickstartPlanning, prerequisites, and validation
Install on a platform you've already chosenInstall the control planePlanning, unless you need to size the deployment
Deploy for a team, one step at a timeThe five phases, starting with phase 1Nothing
Choose a platform or size a deploymentPlan your deploymentInstallation steps
Upgrade a deployment that's already runningUpgradingEverything except the upgrade guidance
Install only the coder command-line clientCoder downloads pageThe 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.

PhaseWhat it answersWhat you finish with
1. Plan your deploymentWhich components run where, how large they need to be, who operates themA deployment shape and a size target you can hand to an infrastructure team
2. Prepare prerequisitesWhat must exist before installation starts, and who owns each pieceDNS, certificates, a database, a license, and an identity provider application
3. Install the control planeHow to install Coder on the platform your team operatesA running Coder deployment you can sign in to
4. Validate your deploymentWhether the deployment is hardened, works, and holds up under loadEvidence that the deployment is ready for real users
5. Operate and maintainHow to keep the deployment healthy, upgraded, and correctly sizedAn 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.

ActorResponsible forAppears in phase
Coder platform ownerThe deployment itself: installation, configuration, upgrades, and support1 to 5
Infrastructure teamClusters, virtual machines, networking, load balancers, and egress rules1 to 4
DNS and TLS ownerThe Coder hostname, the wildcard record for workspace apps, and certificates2
Database administratorPostgreSQL provisioning, sizing, backups, and restore tests2, 4, 5
Identity provider administratorThe OpenID Connect (OIDC) application, claims, and group mappings2
Security and compliance reviewerAudit requirements, network policy, data handling, and sign-off2, 4
Licensing contactPurchasing and renewing the Coder license2
Template authorThe workspace templates developers use once the deployment is running4, 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.