Skip to content

docs: add quick paths to the install landing page and retire the CLI page - #31513

Merged
nickvigilante merged 3 commits into
mainfrom
docs-install-landing-quick-paths
Nov 2, 2026
Merged

nickvigilante merged 3 commits into
mainfrom
docs-install-landing-quick-paths

Conversation

@nickvigilante

@nickvigilante nickvigilante commented Oct 29, 2026 •

Copy link
Copy Markdown
Collaborator

The install landing page presented five phases that had to be read in order, which doesn't fit every install.
This keeps the five-phase structure and adds the flexibility discussed with Ben and Ian: put the options up front, offer shortcuts, and let users skip what doesn't apply.

  • Adds a Choose your path table that sends evaluators to the Quickstart, users with a chosen platform to the control plane pages, and everyone else through the phases in order.
  • Adds a Run Coder on a single server section as the quick option.
    It names what the Quickstart skips (sizing, DNS and TLS through the tunnel, the identity provider, the license, and the external database), explains what the built-in database means, and links to the migration steps for when users outgrow it.
  • Explains each of the five phases in more detail: what it does, who needs it, what you finish with, and when you can skip it.
  • Adds Decisions worth making deliberately for the choices that are costly to change later.

The Slack discussion and the 1:1 described bundled versus external PostgreSQL as irreversible.
The docs already describe a migration path (docs/admin/setup/index.md), so the page calls it costly instead: it needs downtime plus a dump and restore.
Topology, size, and network position come from the existing Plan page.

Retire the CLI install page

coder.com/downloads now covers what docs/install/cli.md offered, so the page is gone:

  • /docs/install/cli redirects to https://coder.com/downloads, and the page is out of the sidebar.
  • Inbound links point where the sentence means: the downloads page for getting the binary, the CLI reference for usage (sessions-tokens.md, creating-templates.md, feature-stages.md), and the Quickstart's install step for running Coder with the install script (aws-marketplace.md).
  • The page's only content the downloads page lacks, installing the CLI from your own deployment (air-gapped, version-matched), moves to a new Install the CLI section in user-guides/workspace-access/index.md.
    The Zed and Claude Desktop guides link there.
  • Winget and the Windows Visual C++ note already live in the Quickstart, so they aren't moved.

This overlaps #31205, which edits install/cli.md, zed.md, and rpm.md.
Whichever merges second needs a rebase, and #31205 should drop its cli.md hunk.

A separate PR can add per-phase "skip if" notes to the phase pages, and the install questionnaire stays a follow-up.

Checks: make lint/emdash, lint/docs-html, lint/docs-manifest, lint/docs-redirects, markdownlint, and Vale.
Vale's remaining findings on changed files are on lines this PR doesn't edit.


🤖 Generated with Coder Agents.

@nickvigilante
nickvigilante marked this pull request as ready for review October 29, 2026 18:27

@ianjevans ianjevans left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Left one comment, but otherwise looks good.

Comment thread docs/install/index.md Outdated
A single-server deployment fits an evaluation, a proof of concept, or a small team.

On a single server, Coder uses its built-in PostgreSQL database unless you set `CODER_PG_CONNECTION_URL`.
That removes the database from your prerequisites, which is the main reason the Quickstart is quick.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is it that simple? Not e.g. sizing K8s nodes and setting up SSO?

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It wasn't. My new agent thinks my previous agent hallucinated, so I made some updates for better accuracy.

Comment thread docs/install/index.md Outdated

| If you want to | Start here | What you skip |
|----------------------------------------------|------------------------------------------------------------|--------------------------------------------------|
| See what Coder does on a single machine | [Quickstart](../get-started/index.md) | Planning, prerequisites, and validation |

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Don't use the word "see". Find another way to word this inclusively.

Comment thread docs/install/index.md Outdated
Comment on lines +11 to +18
| If you want to | Start here | What you skip |
|----------------------------------------------|------------------------------------------------------------|--------------------------------------------------|
| See what Coder does on a single machine | [Quickstart](../get-started/index.md) | Planning, prerequisites, and validation |
| Install on a platform you've already chosen | [Install the control plane](./server/index.md) | Planning, unless you need to size the deployment |
| Deploy for a team, one step at a time | [The five phases](#the-five-phases), starting with phase 1 | Nothing |
| Choose a platform or size a deployment | [Plan your deployment](./plan/index.md) | Installation steps |
| Upgrade a deployment that's already running | [Upgrading](./operate/upgrade.md) | Everything except the upgrade guidance |
| Install only the `coder` command-line client | [Coder CLI](./cli.md) | The rest of this section |

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should point users to coder.com/downloads instead. And as part of this PR, can we retire the CLI page?

Comment thread docs/install/index.md Outdated
That removes the database from your prerequisites, which is the main reason the Quickstart is quick.
It also means the 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 start over.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
When you outgrow a single server, you don't start over.
When you outgrow a single server, you don't need to start over.

Comment thread docs/install/index.md Outdated
It also means the 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 start over.
Move the data to an external PostgreSQL database by following [Migrate from the built-in database to an external database](../admin/setup/index.md#migrate-from-the-built-in-database-to-an-external-database), then read [Plan your deployment](./plan/index.md) to decide how to grow.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Move the data to an external PostgreSQL database by following [Migrate from the built-in database to an external database](../admin/setup/index.md#migrate-from-the-built-in-database-to-an-external-database), then read [Plan your deployment](./plan/index.md) to decide how to grow.
You can move the data to an external PostgreSQL database by following [Migrate from the built-in database to an external database](../admin/setup/index.md#migrate-from-the-built-in-database-to-an-external-database), then read [Plan your deployment](./plan/index.md) to decide how to grow.

@nickvigilante nickvigilante changed the title docs(docs/install): add quick paths and phase guidance to the install landing page docs: add quick paths to the install landing page and retire the CLI page Nov 2, 2026
… landing page

Replace the linear framing with a choose-your-path table, a single-server
option, per-phase guidance on what each phase does and when to skip it,
and a short list of decisions that are costly to change later.

Assisted-by: AI
The single-server section credited the built-in database as the main reason the Quickstart is quick. The Quickstart also skips sizing, DNS and TLS (through the tunnel), the identity provider application, and the license, so name all of them and keep the database point for the backup guidance that follows.
Apply review feedback on the install landing page: reword the Quickstart row without "see", point the CLI-only row at coder.com/downloads, and soften the outgrow paragraph.

Retire docs/install/cli.md, since the downloads page covers its install methods. Redirect /docs/install/cli to coder.com/downloads, remove the page from the manifest, and repoint every inbound link by intent: the downloads page for getting the binary, the CLI reference for usage, and the Quickstart for the install script. The deployment-hosted install script was the page's only unique content, so it moves to a new Install the CLI section in the workspace access guide.
@nickvigilante
nickvigilante force-pushed the docs-install-landing-quick-paths branch from 5bff6d7 to 8ba2a2c Compare November 2, 2026 16:52

@ianjevans ianjevans left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lgtm

@nickvigilante
nickvigilante merged commit 3edce9f into main Nov 2, 2026
28 of 29 checks passed
@nickvigilante
nickvigilante deleted the docs-install-landing-quick-paths branch November 2, 2026 19:23
@github-actions github-actions Bot locked and limited conversation to collaborators Nov 2, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants