Commit Graph
9 Commits
Author SHA1 Message Date
Andrew G. Dunn 020b437ec9 docs: document dropping capabilities for restricted Pod Security (#30271)
Following the suggestion in #22543 to have
`coder.securityContext.capabilities` in `values.yaml` without a default,
this adds it as a commented example, the same way `values.yaml` shows
`env` and `initContainers`, and adds one line to the Kubernetes Security
Reference. Existing deployments don't change on upgrade.

The chart's default security context passes every Pod Security Standards
`restricted` check except capabilities, so a namespace that enforces
`restricted` rejects the pod. Because the example is commented out, the
rendered chart is unchanged:

```console
$ diff main.yaml branch.yaml && echo "renders identical ($(wc -l < branch.yaml) lines)"
renders identical (208 lines)
```

Server-side dry runs of this branch's chart into a namespace labeled
`pod-security.kubernetes.io/enforce=restricted` (GKE, Kubernetes 1.35),
using the pod spec from the rendered Deployment, as is and with the
example uncommented:

```console
$ kubectl create --dry-run=server -n coder -f pod-branch.json
Error from server (Forbidden): error when creating "pod-branch.json": pods "pss-main-branch" is forbidden: violates PodSecurity "restricted:latest": unrestricted capabilities (container "coder" must set securityContext.capabilities.drop=["ALL"])
$ kubectl create --dry-run=server -n coder -f pod-branch-drop.json
pod/pss-main-branch-drop created (server dry run)
```

A v2.37.3 deployment with the value set runs in a `restricted`
namespace, ready with no restarts.

AI involvement: I used an AI assistant to draft this change, and
verified it with the commands above against a running cluster.
2026-10-07 23:18:04 +00:00
Ian Evans 21c1abe9ad docs(docs/install): reformat to one sentence per line (#30438)
Reformats every Markdown page under `docs/install` to the
[one-sentence-per-line
convention](https://github.com/coder/coder/blob/main/docs/.style/style-guide/formatting.md#one-sentence-per-line).
Addresses DOCS-668.

This is a source-layout change only: 28 of the 36 pages change, and
rendered HTML is identical for all of them except three wording fixes.
Three pre-existing em dashes sat on reflowed lines, which `lint/emdash`
flags as new, so they're rewritten with commas or a sentence break
(`operate/upgrade/esr-2.24-2.29-upgrade.md`,
`operate/upgrade/best-practices.md`).

Front matter, fenced code, tables, HTML blocks, and headings are
untouched.

`Coder.OneSentencePerLine` is not enabled for `docs/install` in
`.vale.ini`: the 39 remaining findings are all table rows or code, which
the guide puts out of scope, and enabling the rule would break the
zero-baseline doctrine.

<details>
<summary>Implementation and verification notes</summary>

**Approach.** A throwaway script reflowed each paragraph. Bullet items,
numbered entries, and blockquote lines (including `> [!NOTE]` callouts)
are each their own paragraph; extra sentences in a list item continue on
indented lines, matching `docs/.style/content-guidelines.md`. Sentence
breaks are never inserted inside inline code, link text, URLs, or HTML
tags, and abbreviations such as `e.g.` and `etc.` don't count as
sentence ends. Images that started their own source line stay on their
own line. The script is idempotent: a second pass produces no changes.

**Merge with main.** `main` restructured `docs/install` into plan,
prepare, server, validate, and operate sections after this branch was
cut. The merge takes `main`'s tree and re-runs the reflow over every
page now under `docs/install`, so the branch diff against `main` is
reflow only. `releases/index.md` and `releases/feature-stages.md` moved
out of `docs/install` on `main` and are no longer in scope.

**Verification.**

- Rendered every page with `marked` from `main` and from this branch and
compared normalized HTML: identical except the three em-dash rewrites.
- Vale with `Coder.OneSentencePerLine` forced on for `docs/install`: 277
findings on `main`, 39 on this branch, all in table rows or fenced code.
- A broader sweep for mid-line sentence boundaries and for false splits
(lines starting lowercase, lines ending in an abbreviation) found no
prose hits.
- `markdownlint-cli2`, `markdown-table-formatter --check`, `make
lint/emdash`, and `make pre-commit-light` pass.

</details>

---

*Generated by Coder Agents on behalf of @ianjevans.*
2026-10-06 13:31:35 -07:00
Nick Vigilante 3f408825b5 docs: add playback controls and descriptions to autoplaying videos (#30263)
## Summary

Four docs pages embed autoplaying, looping screencasts with no controls,
so readers cannot pause them (WCAG 2.2.2, Level A). This adds `controls`
and `muted` to each `<video>` and a one-sentence text description after
each video. The renderer-side companion for the beta docs is
coder/docs-engine#203.

## Changes

- Add `controls` and `muted` to the `<video autoplay playsinline loop>`
tag in `external-auth.md`, `open-in-coder.md`,
`ai-coder/agents/index.md`, and `compute-engine.md`. `autoplay`,
`playsinline`, and `loop` stay.
- Add a one-sentence description of each screencast directly below it.
- `extending-templates/external-auth.md` is not in `docs/manifest.json`,
so it is unpublished. It is fixed for consistency.

## Testing

- `pnpm lint-docs` (markdownlint-cli2): 0 errors across 519 files.
- `make lint/emdash`, `go run ./scripts/docshtmlcheck`, `go run
./scripts/styleclaims`: pass.
- The repo pre-commit hook passed.
- Not run: rendering the pages in a browser. The descriptions are
inferred from the surrounding prose and file names, not from watching
the videos.

Linear: [DOCS-1050](https://linear.app/codercom/issue/DOCS-1050)

_Generated by Coder Agents on behalf of @nickvigilante._
2026-10-05 09:35:36 -04:00
Nick Vigilante 4a62b0fc9c docs: add YAML front matter to remaining pages (#30115)
## Summary

Add YAML front matter to the remaining published documentation pages so
all published pages expose a title through front matter.

## Changes

- Add front matter to the 13 published pages that were missing it.
- Preserve the page titles and feature states in the manifest.
- Remove duplicate H1 headings where the front matter supplies the page
title.

## Testing

- `pnpm check-docs` passed.
- Repository pre-commit checks passed.
- Verified all 439 published manifest route entries have YAML front
matter.

Depends on #30109.

Refs DOCS-1124.

This pull request was generated by Coder Agents.
2026-09-29 20:31:27 -04:00
Nick Vigilante d43dd98baf docs: rewrite gerund-leading headings and page titles (#30049)
Rewrites the headings and page titles that `Coder.GerundHeading` flags
as gerund-leading, using the imperative for tasks and the noun form for
concepts.
This PR covers only changes that don't rename a page slug.

## Changes

- Rewrites 121 in-page headings, bringing `Coder.GerundHeading` findings
in `docs/` to zero.
- Adds an empty `<a id="old-slug"></a>` above each renamed heading, so
existing bookmarks and inbound deep links still land on the section.
The legacy IDs were computed with the same slugger the classic renderer
uses (`rehype-slug`), and all 115 that exist on production today match
the live `id` attributes; the other 6 are on pages not published yet.
- Updates the 18 in-docs links that targeted old anchors to use the new
slugs, and the link text that quoted the old heading.
- De-gerunds seven page titles (frontmatter and `manifest.json`) whose
slugs don't change, for example `Upgrading Best Practices` to `Upgrade
best practices`.
- Scopes a Vale exception around the glossary term `Coding agent`, where
"Coding" is an adjective.

## Not in this PR

- **Pages with gerund slugs** (`creating-templates`, `getting-started`,
`working-with-dev-containers`, `cloning-git-repositories`,
`configuring-okta`, and others) keep their current titles, so the title
and slug change together in the slug-rename PR.
  The redirects for those renames come in a third PR.
- **Links outside `docs/`** to old anchors (Go notification strings, an
applied SQL migration, golden files, and the generated `prometheus.md`)
still target old slugs.
They keep working through the legacy anchors, and updating them would
need code changes.

## Known limitation

`coder/docs-engine` prefixes raw-HTML `id` attributes with
`user-content-` (DOM-clobbering protection), and inbound deep links
aren't rewritten.
Once the docs move to docs-engine, these legacy anchors resolve only as
`#user-content-<old-slug>` unless docs-engine adds a fragment fallback.
They work on the current coder.com renderer and on GitHub.

## Testing

- `vale --filter='.Name=="Coder.GerundHeading"' docs`: zero findings,
down from 122.
- `make lint/markdown`, `make lint/docs-html`, `make lint/emdash`, and
the pre-commit hook: all pass.
- Scripted check that every relative `#fragment` link into a changed
file resolves to a heading slug or a legacy anchor (177 links).
- Scripted check that no legacy ID collides with a heading slug on the
same page, and that no untouched heading's duplicate-suffix slug
shifted.

<details>
<summary>Heading renames and legacy anchors (121)</summary>

| File | Old heading | New heading | Legacy anchor |
| --- | --- | --- | --- |
| `admin/integrations/opentofu.md` | Using a custom Terraform binary |
Use a custom Terraform binary | `#using-a-custom-terraform-binary` |
| `admin/monitoring/connection-logs.md` | Capturing/Exporting Connection
Logs | Capture and export connection logs |
`#capturingexporting-connection-logs` |
| `admin/monitoring/metrics.md` | Setting up metrics | Set up metrics |
`#setting-up-metrics` |
| `admin/networking/port-forwarding.md` | Accessing workspace ports |
Access workspace ports | `#accessing-workspace-ports` |
| `admin/networking/port-forwarding.md` | Sharing ports | Share ports |
`#sharing-ports` |
| `admin/networking/port-forwarding.md` | Configuring port protocol |
Configure port protocol | `#configuring-port-protocol` |
| `admin/networking/workspace-proxies.md` | Running on Kubernetes | Run
on Kubernetes | `#running-on-kubernetes` |
| `admin/networking/workspace-proxies.md` | Running on a VM | Run on a
VM | `#running-on-a-vm` |
| `admin/networking/workspace-proxies.md` | Running as a system service
| Run as a system service | `#running-as-a-system-service` |
| `admin/networking/workspace-proxies.md` | Running in Docker | Run in
Docker | `#running-in-docker` |
| `admin/networking/workspace-proxies.md` | Selecting a proxy | Select a
proxy | `#selecting-a-proxy` |
| `admin/security/audit-logs.md` | Capturing/Exporting Audit Logs |
Capture and export audit logs | `#capturingexporting-audit-logs` |
| `admin/security/audit-logs.md` | Purging Old Audit Logs | Purge old
audit logs | `#purging-old-audit-logs` |
| `admin/security/database-encryption.md` | Enabling encryption | Turn
on encryption | `#enabling-encryption` |
| `admin/security/database-encryption.md` | Rotating keys | Rotate keys
| `#rotating-keys` |
| `admin/security/database-encryption.md` | Disabling encryption | Turn
off encryption | `#disabling-encryption` |
| `admin/security/database-encryption.md` | Deleting Encrypted Data |
Delete encrypted data | `#deleting-encrypted-data` |
| `admin/security/secrets.md` | Displaying Secrets | Display secrets |
`#displaying-secrets` |
| `admin/setup/data-retention.md` | Keeping Data Indefinitely | Keep
data indefinitely | `#keeping-data-indefinitely` |
| `admin/setup/index.md` | Migrating from the built-in database to an
external database | Migrate from the built-in database to an external
database |
`#migrating-from-the-built-in-database-to-an-external-database` |
| `admin/setup/index.md` | Configuring Coder behind a proxy | Configure
Coder behind a proxy | `#configuring-coder-behind-a-proxy` |
| `admin/setup/telemetry.md` | Toggling | Turn telemetry on or off |
`#toggling` |
| `admin/templates/creating-templates.md` | Disabling the template
builder | Turn off the template builder |
`#disabling-the-template-builder` |
| `admin/templates/extending-templates/agent-metadata.md` | Managing the
database load | Manage the database load | `#managing-the-database-load`
|
| `admin/templates/extending-templates/docker-in-workspaces.md` |
Authenticating with a Private Registry | Authenticate with a private
registry | `#authenticating-with-a-private-registry` |
| `admin/templates/extending-templates/index.md` | Running scripts on
workspace lifecycle | Run scripts on workspace lifecycle events |
`#running-scripts-on-workspace-lifecycle` |
| `admin/templates/extending-templates/parameters.md` | Validating
parameters | Validate parameters | `#validating-parameters` |
| `admin/templates/extending-templates/prebuilt-workspaces.md` |
Invalidating prebuilds | Invalidate prebuilds |
`#invalidating-prebuilds` |
| `admin/templates/extending-templates/prebuilt-workspaces.md` |
Managing resource quotas | Manage resource quotas |
`#managing-resource-quotas` |
| `admin/templates/extending-templates/prebuilt-workspaces.md` |
Managing prebuild provisioning queues | Manage prebuild provisioning
queues | `#managing-prebuild-provisioning-queues` |
| `admin/templates/extending-templates/prebuilt-workspaces.md` |
Preventing resource replacement | Prevent resource replacement |
`#preventing-resource-replacement` |
| `admin/templates/extending-templates/prebuilt-workspaces.md` |
Preventing prebuild queue contention (recommended) | Prevent prebuild
queue contention (recommended) |
`#preventing-prebuild-queue-contention-recommended` |
| `admin/templates/extending-templates/process-logging.md` | Configuring
custom templates to use workspace process logging | Configure custom
templates to use workspace process logging |
`#configuring-custom-templates-to-use-workspace-process-logging` |
| `admin/templates/extending-templates/process-logging.md` | Viewing
workspace process logs | View workspace process logs |
`#viewing-workspace-process-logs` |
| `admin/templates/extending-templates/process-priority.md` | Verifying
the feature is enabled | Verify the feature is enabled |
`#verifying-the-feature-is-enabled` |
| `admin/templates/extending-templates/resource-metadata.md` | Hiding
resources in the dashboard | Hide resources in the dashboard |
`#hiding-resources-in-the-dashboard` |
| `admin/templates/extending-templates/resource-metadata.md` | Using a
custom resource icon | Use a custom resource icon |
`#using-a-custom-resource-icon` |
| `admin/templates/extending-templates/resource-ordering.md` | Using
"order" property | Use the "order" property | `#using-order-property` |
| `admin/templates/extending-templates/resource-persistence.md` |
Disabling persistence | Turn off persistence | `#disabling-persistence`
|
| `admin/templates/index.md` | Extending templates | Extend templates |
`#extending-templates` |
| `admin/templates/managing-templates/change-management.md` | Testing
and Publishing Coder Templates in CI/CD | Test and publish Coder
templates in CI/CD | `#testing-and-publishing-coder-templates-in-cicd` |
| `admin/templates/managing-templates/index.md` | Creating templates |
Create templates | `#creating-templates` |
| `admin/templates/managing-templates/index.md` | Editing templates |
Edit templates | `#editing-templates` |
| `admin/templates/managing-templates/index.md` | Updating templates |
Update templates | `#updating-templates` |
| `admin/templates/troubleshooting.md` | Debugging the startup script |
Debug the startup script | `#debugging-the-startup-script` |
| `admin/users/groups-roles.md` | Creating custom roles | Create custom
roles | `#creating-custom-roles` |
| `admin/users/index.md` | Configuring SSO | Configure SSO |
`#configuring-sso` |
| `admin/users/index.md` | Resetting a password on Kubernetes | Reset a
password on Kubernetes | `#resetting-a-password-on-kubernetes` |
| `admin/users/quotas.md` | Establishing Costs | Establish costs |
`#establishing-costs` |
| `admin/users/quotas.md` | Establishing Budgets | Establish budgets |
`#establishing-budgets` |
| `admin/users/sessions-tokens.md` | Creating tokens with scopes |
Create tokens with scopes | `#creating-tokens-with-scopes` |
| `ai-coder/agent-firewall/index.md` | Getting Started with Agent
Firewall | Get started with Agent Firewall |
`#getting-started-with-agent-firewall` |
| `ai-coder/agent-firewall/index.md` | Viewing Audit Logs | View audit
logs | `#viewing-audit-logs` |
| `ai-coder/agent-firewall/nsjail/k8s.md` | Running without user
namespaces | Run without user namespaces |
`#running-without-user-namespaces` |
| `ai-coder/agent-firewall/version.md` | Using Coder Before v2.30.0 with
Claude Code Module v4.7.0+ | Coder before v2.30.0 with Claude Code
module v4.7.0+ |
`#using-coder-before-v2300-with-claude-code-module-v470` |
| `ai-coder/agent-firewall/version.md` | Using Claude Code Module Before
v4.7.0 | Claude Code module before v4.7.0 |
`#using-claude-code-module-before-v470` |
| `ai-coder/agents/getting-started.md` | Providing feedback | Provide
feedback | `#providing-feedback` |
| `ai-coder/agents/models.md` | Managing personal API keys | Manage
personal API keys | `#managing-personal-api-keys` |
| `ai-coder/agents/models.md` | Removing a personal key | Remove a
personal key | `#removing-a-personal-key` |
| `ai-coder/agents/models.md` | Using an LLM proxy | Use an LLM proxy |
`#using-an-llm-proxy` |
| `ai-coder/agents/platform-controls/git-providers.md` | Checking logs |
Check logs | `#checking-logs` |
| `ai-coder/ai-gateway/audit.md` | Navigating the UI | Navigate the UI |
`#navigating-the-ui` |
| `ai-coder/ai-gateway/audit.md` | Conducting a forensic audit | Conduct
a forensic audit | `#conducting-a-forensic-audit` |
| `ai-coder/ai-gateway/clients/jetbrains.md` | Using the AI Assistant |
Use the AI Assistant | `#using-the-ai-assistant` |
| `install/operate/upgrade/best-practices.md` | Diagnosing liveness
probe issues | Diagnose liveness probe issues |
`#diagnosing-liveness-probe-issues` |
| `install/operate/upgrade/best-practices.md` | Recovering from failed
database migrations | Recover from failed database migrations |
`#recovering-from-failed-database-migrations` |
| `install/operate/upgrade/esr-2.24-2.29-upgrade.md` | Upgrading |
Upgrade recommendations | `#upgrading` |
| `install/operate/upgrade/esr-2.29-2.34-upgrade.md` | Upgrading |
Upgrade recommendations | `#upgrading` |
| `install/prepare/licensing.md` | Adding your license key | Add your
license key | `#adding-your-license-key` |
| `install/server/cloud/azure-vm.md` | Creating and Uploading Your First
Template | Create and upload your first template |
`#creating-and-uploading-your-first-template` |
| `install/server/cloud/compute-engine.md` | Configuring the control
plane | Configure the control plane | `#configuring-the-control-plane` |
| `reference/releases.md` | Installing stable | Install stable |
`#installing-stable` |
| `start/first-workspace.md` | Creating your first coder workspace |
Create your first Coder workspace |
`#creating-your-first-coder-workspace` |
| `start/local-deploy.md` | Setting up a Coder deployment | Set up a
Coder deployment | `#setting-up-a-coder-deployment` |
| `tutorials/best-practices/organizations.md` | Managing Organizations
at Scale | Manage organizations at scale |
`#managing-organizations-at-scale` |
| `tutorials/example-guide.md` | Adding Photos | Add photos |
`#adding-photos` |
| `tutorials/example-guide.md` | Setting the author data | Set the
author data | `#setting-the-author-data` |
| `tutorials/example-guide.md` | Setting up the routes | Set up the
routes | `#setting-up-the-routes` |
| `tutorials/persistent-shared-workspaces.md` | Finding shared
workspaces | Find shared workspaces | `#finding-shared-workspaces` |
| `tutorials/reverse-proxy-caddy.md` | Getting started | Get started |
`#getting-started` |
| `tutorials/reverse-proxy-caddy.md` | Generating wildcard certificates
| Generate wildcard certificates | `#generating-wildcard-certificates` |
| `tutorials/reverse-proxy-nginx.md` | Adding Coder deployment subdomain
| Add the Coder deployment subdomain |
`#adding-coder-deployment-subdomain` |
| `tutorials/testing-templates.md` | Creating the headless user | Create
the headless user | `#creating-the-headless-user` |
| `user-guides/desktop/desktop-connect-sync.md` | Accessing web apps in
a secure browser context | Access web apps in a secure browser context |
`#accessing-web-apps-in-a-secure-browser-context` |
| `user-guides/desktop/index.md` | Testing Your Connection | Test your
connection | `#testing-your-connection` |
| `user-guides/desktop/index.md` | Getting Help | Get help |
`#getting-help` |
| `user-guides/desktop/index.md` | Uninstalling | Uninstall Coder
Desktop | `#uninstalling` |
| `user-guides/devcontainers/index.md` | Getting started | Get started |
`#getting-started` |
| `user-guides/devcontainers/troubleshooting-dev-containers.md` |
Finding your dev container agent | Find your dev container agent |
`#finding-your-dev-container-agent` |
| `user-guides/devcontainers/troubleshooting-dev-containers.md` |
Getting more help | Get more help | `#getting-more-help` |
| `user-guides/devcontainers/working-with-dev-containers.md` | Using the
Coder CLI | Use the Coder CLI | `#using-the-coder-cli` |
| `user-guides/devcontainers/working-with-dev-containers.md` | Using
OpenSSH (config-ssh) | Use OpenSSH (config-ssh) |
`#using-openssh-config-ssh` |
| `user-guides/devcontainers/working-with-dev-containers.md` | Exposing
ports on the parent workspace | Expose ports on the parent workspace |
`#exposing-ports-on-the-parent-workspace` |
| `user-guides/devcontainers/working-with-dev-containers.md` |
Rebuilding dev containers | Rebuild dev containers |
`#rebuilding-dev-containers` |
| `user-guides/shared-workspaces.md` | Getting Started | Get started |
`#getting-started` |
| `user-guides/shared-workspaces.md` | Sharing your Workspace | Share
your workspace | `#sharing-your-workspace` |
| `user-guides/shared-workspaces.md` | Using a shared workspace | Use a
shared workspace | `#using-a-shared-workspace` |
| `user-guides/shared-workspaces.md` | Accessing workspace apps in
shared workspaces | Access workspace apps in shared workspaces |
`#accessing-workspace-apps-in-shared-workspaces` |
| `user-guides/workspace-access/emacs-tramp.md` | Connecting To A
Workspace | Connect to a workspace | `#connecting-to-a-workspace` |
| `user-guides/workspace-access/emacs-tramp.md` | Using SSH | Use SSH |
`#using-ssh` |
| `user-guides/workspace-access/index.md` | Running remote commands with
quoting | Run remote commands with quoting |
`#running-remote-commands-with-quoting` |
| `user-guides/workspace-access/jetbrains/gateway.md` | Configuring the
Gateway plugin to use internal certificates | Configure the Gateway
plugin to use internal certificates |
`#configuring-the-gateway-plugin-to-use-internal-certificates` |
| `user-guides/workspace-access/jetbrains/gateway.md` | Using an
existing JetBrains installation in the workspace | Use an existing
JetBrains installation in the workspace |
`#using-an-existing-jetbrains-installation-in-the-workspace` |
| `user-guides/workspace-access/port-forwarding.md` | Accessing
workspace ports | Access workspace ports | `#accessing-workspace-ports`
|
| `user-guides/workspace-access/port-forwarding.md` | Sharing ports |
Share ports | `#sharing-ports` |
| `user-guides/workspace-access/port-forwarding.md` | Configuring port
protocol | Configure port protocol | `#configuring-port-protocol` |
| `user-guides/workspace-access/vscode.md` | Using the public extensions
marketplaces | Use the public extensions marketplaces |
`#using-the-public-extensions-marketplaces` |
| `user-guides/workspace-access/vscode.md` | Adding extensions to custom
images | Add extensions to custom images |
`#adding-extensions-to-custom-images` |
| `user-guides/workspace-access/vscode.md` | Installing extensions using
its `vsix` file at the command line | Install extensions using a `vsix`
file at the command line |
`#installing-extensions-using-its-vsix-file-at-the-command-line` |
| `user-guides/workspace-access/vscode.md` | Installing from a
marketplace at the command line | Install from a marketplace at the
command line | `#installing-from-a-marketplace-at-the-command-line` |
| `user-guides/workspace-access/vscode.md` | Using VS Code Desktop | Use
VS Code Desktop | `#using-vs-code-desktop` |
| `user-guides/workspace-access/web-terminal.md` | Accessing the
Terminal | Access the terminal | `#accessing-the-terminal` |
| `user-guides/workspace-lifecycle.md` | Stopping workspaces | Stop
workspaces | `#stopping-workspaces` |
| `user-guides/workspace-lifecycle.md` | Deleting workspaces | Delete
workspaces | `#deleting-workspaces` |
| `user-guides/workspace-management.md` | Creating workspaces | Create
workspaces | `#creating-workspaces` |
| `user-guides/workspace-management.md` | Updating workspaces | Update
workspaces | `#updating-workspaces` |
| `user-guides/workspace-management.md` | Updating via the CLI | Update
with the CLI | `#updating-via-the-cli` |
| `user-guides/workspace-management.md` | Starting and stopping
workspaces | Start and stop workspaces |
`#starting-and-stopping-workspaces` |
| `user-guides/workspace-management.md` | Repairing workspaces | Repair
workspaces | `#repairing-workspaces` |
| `user-guides/workspace-scheduling.md` | Working hours | Work schedule
| `#working-hours` |
| `user-guides/workspace-scheduling.md` | Basing solely on activity
detection | Rely solely on activity detection |
`#basing-solely-on-activity-detection` |

</details>

<details>
<summary>Plan</summary>

The de-gerund work ships as three PRs:

1. This PR: in-page headings and page titles that do not require a page
slug rename.
1. Page slug renames for pages whose filenames are gerunds.
1. Redirects for the renamed slugs.

Heading rewrites follow the style guide section "No gerund-leading
headings": imperative for task headings, noun form for concept headings,
sentence case, and "turn on"/"turn off" instead of "enable"/"disable"
per word-choice guidance.
The legacy anchor sits on its own line above the heading (with a blank
line between) rather than inside the heading, so it does not leak into
heading text, TOC entries, or Fumadocs slugs.

</details>

---

_Generated by Coder Agents on behalf of @nickvigilante._
2026-09-28 13:40:07 -04:00
Nick Vigilante 88aa2cc373 feat: enable Coder.UnitSpacing (#29944)
## Summary

Adds `Coder.UnitSpacing`, a Vale rule that enforces the style guide's
[non-breaking space between number and
unit](https://github.com/coder/coder/blob/main/docs/.style/style-guide/numbers-units-and-dates.md#non-breaking-space-between-number-and-unit)
policy.
Until now, the guide pointed at `Google.Units (planned)`, but that rule
accepts a regular space, so it can't enforce the policy.

Resolves [DOCS-1072](https://linear.app/codercom/issue/DOCS-1072).

## Changes

- **Cleanup commit**: replaces the regular space (or missing space) with
`&nbsp;` in 189 prose findings across 55 files. One config default,
`(default: 15s)`, moves to code font instead, as the guide requires for
configuration values. One table row that was realigned also swaps a
pre-existing en dash for a hyphen, since `lint/emdash` checks changed
lines.
- **Enable commit**: adds `docs/.style/styles/Coder/UnitSpacing.yml` at
`warning`, updates the enforcement footer in
`numbers-units-and-dates.md`, and updates the coverage tables in the
style guide README.
- **Reflow commit**: every hard-wrapped paragraph the cleanup touched
(45 paragraphs in 29 files) is rewrapped to one sentence per line.
Joining lines exposed units split across a line break, which now use
`&nbsp;`, and two em dashes on rewritten lines are reworded.
- **Rule fix commit**: the token now matches ASCII whitespace, including
a newline, between the number and the unit, so a hard-wrapped paragraph
can't hide a missing `&nbsp;`. The class is spelled out because Vale's
`\s` is Unicode and would match U+00A0. Vale can't locate a match that
spans list indentation or a blockquote marker, so splits there still go
unreported.
- **Rule count sync**: the tooling paragraph in the style guide README
now reads 79 rules, 9 tool-checked, to match the coverage table. The 79
corrects drift already on `main` since #29758; the 9 is this PR's new
rule.
- `.vale.ini` turns the rule off for pages generated from Go source:
`docs/reference/{api,cli}/*.md`, `configuration-reference.md`, and
`prometheus.md`. That text comes from flag descriptions, Swagger
comments, and metric help text, which also render outside Markdown,
where `&nbsp;` would show up literally.

<details>
<summary>Rule design decisions</summary>

- An `existence` rule matches `\d+(\.\d+)?` followed by a regular space
or no space, then a unit from a curated list (time, data size,
bandwidth, frequency, vCPU/CPU/cores).
- Vale renders Markdown before matching, so `&nbsp;` and a literal
U+00A0 both pass. Code spans and fences are skipped.
- Hyphenated compound modifiers (`12-hour clock`) don't match, because
the token allows only a space or nothing between the number and the
unit.
- Exceptions cover HTTP status plurals (`413s`) and decades (`1990s`).
- Severity is `warning`, because the unit list is curated and a count
followed by a unit-like word can still be a judgment call.
- Alternative considered: a `BlockIgnores` pattern for the `<!-- Code
generated ... -->` regions. I didn't use it because it would silence
every rule in those regions, not just this one.

</details>

## Testing

- Ran the rule against fixtures: `30 seconds`, `150ms`, `4 vCPU` in a
table, and `16` / `GB` split across lines in a paragraph all flag.
`30&nbsp;seconds`, literal U+00A0, `12-hour`, `413s`, `1990s`, and ``
`30s` `` don't.
- `vale docs/` reports 0 `Coder.UnitSpacing` findings, and the counts
for every other rule match `main`.
- A scratch config with `Coder.OneSentencePerLine` turned on reports 0
findings on changed lines.
- `make lint/markdown`, `make lint/style-claims`, `make lint/emdash`,
and the `pre-commit-light` hook pass.

<details>
<summary>CI flake note</summary>

`Storybook` failed on b3c53b6874 after capturing all 3,421 snapshots,
when the Pixel build was marked `failed` during finalization. This PR
changes no files under `site/`. The re-run failed the same way, and
`Storybook` is failing in the same Pixel step on the latest `main`
commits, so this isn't caused by this PR.

</details>

---

*Generated by [Coder Agents](https://coder.com/docs/ai-coder/agents) on
behalf of @nickvigilante.*
2026-09-28 12:29:40 -04:00
Eric Paulsen aa87166c2f docs: fix step order and values.yaml in Azure App Gateway guide (#29927) 2026-09-25 18:07:17 +01:00
Nick Vigilante 9afdea4808 docs(docs): document RPM install on RHEL-family Linux (#29295)
## Summary

Coder ships `.rpm` assets with every release and `install.sh` routes the
RHEL family to `install_rpm()`, but no public page said so. The only
page that named RHEL was the uninstall page. This adds an RPM install
page for the control plane.

New page `docs/install/server/rpm.md`:

- Supported distribution matrix for RHEL 8/9/10, Rocky, AlmaLinux,
CentOS Stream, Amazon Linux, Fedora, and openSUSE, with the
`ID`/`ID_LIKE` detection that makes derivatives work.
- Install tabs for the install script, `dnf install`, and `rpm -U`.
- What the package lays down: `/usr/bin/coder`,
`/etc/coder.d/coder.env`, `coder.service`,
`coder-workspace-proxy.service`, and the unprivileged `coder` user.
- Configure-then-start ordering, because `coder.service` carries
`ConditionFileNotEmpty=/etc/coder.d/coder.env` and won't start against
an empty config.
- SELinux caveat for Docker/Podman inside workspaces on RHEL nodes,
linking the existing guidance instead of duplicating it.
- Iron Bank UBI9-minimal pointer for hardened environments, scoped
correctly as a container image rather than an RPM path.

Supporting edits: manifest entry under "3. Install the control plane"
between OpenShift and Cloud Providers, a row in the platform table on
`install/server/index.md`, and a pointer from `install/cli.md`.

## Placement

The page sits at `docs/install/server/rpm.md`, as a sibling of Docker,
Kubernetes, Rancher, and OpenShift, rather than under community install
methods: RPMs are officially built and shipped, not an unofficial
method. It is a control-plane deployment page, not CLI download content,
so it is out of scope for the CLI-retirement work.

## Verification

Claims on the page were checked against real RHEL-family images, not
just the install script:

| Check | Method | Result |
|-------|--------|--------|
| `ID` and `ID_LIKE` per distribution | `docker run <image> sh -c '.
/etc/os-release; ...'` across UBI 8/9/10, Rocky 9, Alma 9/10, CentOS
Stream 9/10, Amazon Linux 2/2023, Fedora, openSUSE Leap and Tumbleweed |
Every RHEL-family image lists `fedora` in `ID_LIKE`; both openSUSE
variants list `opensuse`. Matches the `distro()` branch in `install.sh`
|
| `dnf install ./coder_*.rpm` | Rocky Linux 9 container | Installs
cleanly |
| Package contents | `rpm -ql coder` | `/usr/bin/coder`,
`/etc/coder.d/coder.env`, `coder.service`,
`coder-workspace-proxy.service` |
| Service account and start condition | Installed unit file | Runs as
`coder:coder`; `ConditionFileNotEmpty=/etc/coder.d/coder.env` |
| Architectures | `.github/workflows/release.yaml` | `amd64`, `armv7`,
`arm64` |

Not verified: `systemctl enable --now coder` against a live database,
since the containers used for verification have no init system. The
`systemctl is-active` output on the page is standard systemd output,
flagged here for the reviewer.

Lint: `make lint/markdown`, `make lint/emdash`, and `make lint/prose`
all clean on the changed files; `pnpm run format-docs` applied.

<details>
<summary>Implementation plan and decision log</summary>

### Style guide application

The first revision of this page was drafted from sibling install pages
rather than from the style guide, and was rewritten against
[`docs/.style/content-guidelines.md`](https://github.com/coder/coder/blob/main/docs/.style/content-guidelines.md)
and the prose style guide. What changed: one sentence per source line,
declared audience and outcome in the opening paragraph, numbered
procedures with one instruction per step and conditions stated first,
`refer to` instead of `see`, `sh` fences instead of `shell`, H3 tab
headings, non-breaking space between number and unit, and `Learn more`
instead of `Next steps`.

### Decisions

- **No version numbers or FIPS certification claims for Iron Bank.** The
tags in `scripts/ironbank/hardening_manifest.yaml` are stale (`0.15.3`);
documenting them would re-create the drift. The page links the registry
and names the UBI9-minimal base only.
- **Iron Bank framed as a container path.** It is a container image, so
the page routes readers to Kubernetes/OpenShift rather than implying it
is an alternative to the RPM.
- **Dropped an unverified SELinux claim.** An earlier draft asserted
that the control plane runs under enforcing mode with no policy changes.
That was not tested, so it is gone. The section now covers only the
workspace container-runtime case, which links to existing verified
guidance.
- **`ID_LIKE` values kept out of the table.** They vary by version (RHEL
8/9 report `fedora`, RHEL 10 reports `centos fedora`), so the table
lists `ID` and the prose states the invariant the install script
actually matches on.
- **Minimal edit to `install/cli.md`.** That file is slated for deletion
in the Install restructure, so it gets a pointer and nothing more.

### Rebase onto the install spine restructure

The install spine restructure landed on `main` while this PR was open
and removed the install-method tabs on `install/index.md` that the first
revision pointed from. The branch was rebased and squashed onto it: the
page moved from `docs/install/rpm.md` to `docs/install/server/rpm.md`,
every relative link was repointed at the new locations
(`../plan/sizing/index.md`, `../prepare/airgap.md`,
`../operate/upgrade.md`, `../operate/uninstall.md`,
`./kubernetes/index.md`), the install script snippet picked up the
standardized `curl -fsSL` flags, and discovery moved from the removed
`install/index.md` tabs to the platform table on
`install/server/index.md`. The prose is otherwise unchanged.

### Follow-ups tracked elsewhere

The install spine has no other bare-host or Linux-package option under
platforms; every other entry is a container platform or a cloud VM. Open
question recorded on the IA proposal: whether this generalizes to a
single "Linux host (system packages)" page covering `.deb` and `.apk`
too.

</details>

---

Linear:
[DOCS-886](https://linear.app/codercom/issue/DOCS-886/document-support-for-running-coder-on-red-hat-linux)

🤖 Generated with Coder Agents on behalf of @nickvigilante.
2026-09-25 11:47:34 -04:00
Nick Vigilante d5a6047879 docs: restructure Install into the five phase deployment spine (#29304)
Restructures the Install section into the five-phase deployment spine,
so the reading order matches the order a deployment actually happens:
**plan, prepare, install, validate, operate.** Today the first thing a
reader sees is a shell command, and architecture and sizing sit
downstream in Administration, after the point where they would have been
useful.

Resolves [DOCS-869](https://linear.app/codercom/issue/DOCS-869). Part of
[DOCS-685](https://linear.app/codercom/issue/DOCS-685) and
[DOCS-738](https://linear.app/codercom/issue/DOCS-738).

> [!IMPORTANT]
> **Stacked on [#28960](https://github.com/coder/coder/pull/28960)**
(DOCS-871, terminology). Base is that branch, not `main`. Retarget to
`main` after it merges.
>
> **Paired with coder/coder.com
[#1077](https://github.com/coder/coder.com/pull/1077)**, which must
merge **first**. Without it, every inbound link to a moved page 404s in
the gap.

## Deliberately mechanical

No prose changes. The only edits inside moved pages are relative link
and image path repairs, so the diff reads as renames. That is the point:
this is the highest link-breakage change in the project, and it should
be reviewable as such.

The prose work is [DOCS-868](https://linear.app/codercom/issue/DOCS-868)
(phase overview, architecture rewrite, sizing split, actor table) and
[DOCS-872](https://linear.app/codercom/issue/DOCS-872) (new pages).

## The new spine

```text
Install and deploy Coder            /install
├── Coder CLI                                   [unchanged, retired by DOCS-870]
├── 1. Plan your deployment
│   ├── Architecture and components             [from admin/infrastructure]
│   └── Coder Validated Architecture            [from admin/infrastructure]
│       └── 1k / 2k / 3k / 10k users
├── 2. Prepare prerequisites
│   ├── Licensing                               [from admin/licensing]
│   ├── Air-gapped deployments                  [from install/airgap]
│   └── Mirror images and registries            [from install/registry-mirror-artifactory]
├── 3. Install the control plane
│   ├── Docker / Kubernetes / Rancher / OpenShift
│   ├── Cloud marketplace and VM images
│   └── Unofficial install methods
├── 4. Validate your deployment
│   └── Scale testing                           [from admin/infrastructure]
│       ├── Scale test utility
│       └── Scaling best practices
└── 5. Operate and maintain
    ├── External provisioners                   [from admin/provisioners]
    ├── Upgrading (+ best practices, ESR guides)
    └── Uninstall
```

Leaving Install: release channels become `reference/releases`, feature
stages become `reference/feature-stages`.

`docs/admin/infrastructure/` is gone entirely, which is what DOCS-738
recommended.

## Numbers

- 31 pages moved, all as `git mv` renames.
- 1 page deleted: `admin/infrastructure/index.md`, whose content was a
one-line section blurb.
- 5 new placeholder index pages, one per phase, each a sentence of
orientation plus `<children></children>`. The nav schema requires a path
on every entry, so a phase cannot exist without one.
- 265 relative links and asset paths repaired across 57 files.
- `docs/manifest.json` restructured. Entry count goes 460 to 464: plus 5
stubs, minus the deleted Infrastructure entry.

## Reviewer attention, please

**The redirects PR repairs 19 existing redirects, not just adds new
ones.** This was the surprise. `redirects.json` already had entries
whose *destinations* pointed at pages this PR moves, so they would have
started redirecting to 404s. Examples:
`/docs/architecture/architecture`, `/docs/admin/architectures`,
`/docs/scaling/scale-testing`, `/docs/licensing`, `/docs/enterprise`,
`/docs/install/offline`, `/docs/platforms`, `/docs/install/1-click`,
`/docs/admin/upgrade`, `/docs/install/cloud/ec2`, and both
`feature-stages` aliases. All 19 are fixed in the paired PR.

**This PR touches `scripts/`, so it is not docs-only.** Two release
tools write to paths that moved and would have broken silently at
release time:

- `scripts/update-release-calendar.sh`: `DOCS_FILE` now points at
`docs/reference/releases.md`.
- `scripts/releaser/docs.go`: `releasesFile`, and also `kubernetesFile`
and `rancherFile`, which pointed at `docs/install/kubernetes.md` and
`docs/install/rancher.md`.

<details>
<summary>Deliberate scope decisions</summary>

- **Self-managed vs cloud grouping is flattened.** The reconciled IA
nested platform pages under a "Self-managed platforms" parent. That
would need two more placeholder index pages for groups with no content
yet, so the platform pages sit directly under Phase 3 and the grouping
lands with the DOCS-868 prose.
- **Release-notes URLs left alone.** `scripts/releaser/release.go` and
`scripts/release/generate_release_notes.sh` embed
`https://coder.com/docs/install/releases` and `/docs/install/upgrade` in
release-note templates. The redirects cover them, and changing the
strings would require updating Go test fixtures in
`scripts/release/main_internal_test.go`. Better as its own change.
- **In-product doc links left alone.** Several `site/src` pages link to
`coder.com/docs/admin/provisioners` and similar. Those are absolute
URLs, so the redirects cover them. Updating them is a frontend change
that would pull frontend review into a docs restructure.
- **`admin/security/audit-logs.md` line 237** is hand-written prose
below the generated table, and its `../licensing/index.md` link had to
move with the licensing page. Verified `make gen` does not revert it.
- **`reference/feature-stages.md`** has generated blocks whose relative
links changed depth with the move. The generator named in its own marker
comment (`scripts/release/docs_update_feature_stages.sh`) no longer
exists in the repo, so those links were repaired by hand and the file is
effectively hand-maintained. Worth its own issue.
- **`install/cli.md` keeps its nav slot** here. DOCS-870 retires it.

</details>

## Verification

| Check | Result |
|---|---|
| Broken relative link scan | 0 in `install/`, `admin/`, `reference/`.
21 remain, all pre-existing illustrative examples in
`docs/.style/style-guide/**` and one malformed URL in `docs/README.md` |
| `make gen` | clean, manifest not clobbered, phase structure intact |
| `make lint/markdown` | pass, 508 files, 0 errors |
| `make lint/emdash` | pass |
| `make lint/docs-html` | pass |
| `make lint/prose` | pass, 1 intentional demo error, no new findings |
| `make pre-commit` | pass, including `lint/go`, `lint/ts`,
`lint/shellcheck`, and a slim build |
| Manifest audit | every path resolves to a file on disk; entry-by-entry
diff shows only the expected moves |

Generated with Coder Agents on behalf of @nickvigilante.


<details>
<summary>CI note: doc-check failure is infrastructure, not this
PR</summary>

`Analyze PR for Documentation Updates Needed` fails before it reviews
anything: the Coder account behind `agents-chat-action` returns `User is
not active (status = "suspended")`. It isn't a required check.
`check-docs` (linkspector) and every other check pass on `58ed9e3e4b`.

_CI note added by Coder Agents on behalf of @nickvigilante._
</details>
2026-09-24 13:51:38 -04:00