Skip to content

docs(install): route the install landing pages to the control plane guides - #32405

Open
nickvigilante wants to merge 2 commits into
vigilante/docs-1567-airgapped-k3s-quickstartfrom
vigilante/docs-1568-rewrite-the-install-landing-page-clear
Open

nickvigilante wants to merge 2 commits into
vigilante/docs-1567-airgapped-k3s-quickstartfrom
vigilante/docs-1568-rewrite-the-install-landing-page-clear

Conversation

@nickvigilante

Copy link
Copy Markdown
Collaborator

Summary

Rework the install landing pages so a reader who wants the control plane right away can see where to go, without reading the planning phases first.
The sidebar order and every existing page URL stay the same; the only sidebar change is one new page.

Depends on #31869 (the air-gapped K3s tutorial), which this PR is stacked on and links to.
Refs DOCS-1568 and DOCS-1570.

Changes

  • install/index.md: leads with "Install the control plane now", which has three questions (internet access, Kubernetes or container or host, cloud or on premises) and a list of platform guides with Kubernetes recommended.
    It adds an offline subsection that points to the air-gap page and the K3s tutorial, a "Choose your path" table, a first-template step, and a "Move from evaluation to production" section.
    The five phases move below the install path and become a table with a "When you can skip it" column.
  • New install/server/requirements.md (Installation requirements): control plane CPU and memory, PostgreSQL, platform versions, network, internet access, and license, each traced to code or the existing platform pages.
    It's added as the first child of Install the control plane.
  • install/server/index.md: platform table gains a "Where the control plane runs" column (Rancher and OpenShift listed as Kubernetes), plus an offline section and a first-template step.
  • install/server/kubernetes/index.md: intro names EKS, AKS, GKE, K3s, and OpenShift, and points offline clusters to the air-gap page and the K3s tutorial.
  • install/server/cloud/index.md: sends existing EKS, AKS, and GKE clusters to the Kubernetes guide, notes that the AWS Marketplace guide creates a new EKS cluster, and fixes the Azure tab, which said GKE instead of AKS.
  • install/plan/index.md and install/prepare/index.md: planning reads as a recommendation, not a requirement, and Prepare links to the requirements page.

Decisions for review

  1. Rancher and OpenShift read as Kubernetes options.
    This reverses what I proposed in the Nov 4 install review (Rancher with container runtimes, OpenShift with Linux).
    Both guides install the Helm chart on a cluster, so a reader looking for Kubernetes needs to find them.
    This PR only changes the table labels and landing page wording; no pages move.
  2. Requirements page placement. It sits under Install the control plane, not under Prepare, so the install path shows it first.
    Prepare links to it.
  3. Cards. The landing page uses a plain link list. docs-engine can't render cards on coder/coder pages yet (DOCS-1795).

Not in this PR

  • New pages that need a tested run first: create your first template (DOCS-1783), an air-gapped Helm install on EKS or AKS (DOCS-1798), and a small reference architecture (DOCS-1572).
  • Sidebar moves and renames (DOCS-1569).
  • A pre-existing error on a page this PR links to: prepare/airgap.md says the built-in database downloads PostgreSQL from repo1.maven.org, but cli/server.go uses repo.maven.apache.org.

Known tradeoff: platform versions (Kubernetes 1.19, Helm 3.5, and so on) now appear on both the requirements page and each platform page, so a version bump has to update both.

Testing

  • make gen/docs-manifest and make fmt/markdown.
  • make lint/emdash lint/docs-html lint/docs-manifest lint/markdown lint/docs-redirects: all pass.
  • Vale on the seven changed pages: 0 errors and 0 warnings on added lines.
  • A relative link and anchor check on the changed pages: no broken links.
    The K3s tutorial links resolve only on top of docs: add an air-gapped K3s install tutorial #31869.
  • doc-check skill in author self-check mode: the only blocking finding was the merge order dependency on docs: add an air-gapped K3s install tutorial #31869.
    I applied the suggestions on Docker database wording, the wildcard TLS certificate, the Quickstart time, memory units, and the platform question wording.
Plan and decision log

Request. Add pages where they're needed, and update the existing landing pages so it's obvious where to go to install the control plane right away.
Don't rearrange the sidebar or rename pages.

Inputs.

  • The install section skeleton IA draft in Notion (Docs proposals), which recommends Kubernetes as the golden path and air-gap first.
  • Feedback from the Nov 4 install docs review with Stephen Kirby and Ben, the Nick and Ian 1:1 (Nov 4), and the Nick and Ben 1:1 (Nov 5).

What the feedback changed.

  • Kirby's three questions (network-gapped, cloud or on premises, VMs or containers) now open the landing page.
  • Kirby's point was "plan once, deploy once": planning matters, but most of the lost time comes after IT approval.
    So the landing page lets readers install first and keeps Plan and Prepare visible as recommendations, with a "When you can skip it" column, rather than burying them.
  • The review called out the missing path from evaluation to production.
    The landing page now has a "Move from evaluation to production" section and a matching row in "Choose your path".
  • Kirby's golden path is an enterprise past approval installing with Helm on air-gapped EKS or AKS.
    The K3s tutorial covers single-node evaluation only, so that gap is filed as DOCS-1798 instead of being written here without a tested run.
  • A reader checking whether Coder fits (the fourth Mattermost persona) gets a "Choose your path" row that points to the requirements and architecture pages.

Choices made.

  • Requirements traced to code: Helm chart default resources (helm/libcoder/templates/_coder.yaml), Kubernetes version (helm/coder/Chart.yaml kubeVersion), built-in PostgreSQL download (cli/server.go), and the Kubernetes starter template's code-server install (examples/templates/kubernetes/main.tf).
  • The "1-hour Kubernetes quick start" naming from the review is not used yet.
    The K3s page title belongs to docs: add an air-gapped K3s install tutorial #31869, and the time target needs a timed run.
  • Ian's suggestion to use includes for repeated content (such as the air-gap Dockerfile) is deferred.
    This PR repeats only short routing sentences.

This PR was generated by Coder Agents on behalf of @nickvigilante.

…uides

Lead the install landing page with the platform choices, so a reader who
wants the control plane now can start without reading the planning
phases first. Add an installation requirements page, point offline
deployments to the air-gapped guide and the K3s tutorial, and point
existing cloud clusters to the Kubernetes guide.

Refs DOCS-1568
Separate Kubernetes from single-host containers in the platform
questions, note that the Docker guide supports an external database,
and add the TLS certificate that a wildcard access URL needs.

Refs DOCS-1568
@linear-code

linear-code Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

DOCS-1570

DOCS-1568

@nickvigilante
nickvigilante marked this pull request as ready for review November 18, 2026 18:11

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant