Files
coder[bot]andNick Vigilante f97eee3c49 docs: redistribute tutorials and rename top-level sidebar sections (#31647)
> [!NOTE]
> Generated by Coder Agents. The branch and this description were
written by an AI agent and need human review.

## Summary

Third of three stacked PRs for the docs IA overhaul (Proposal 1,
sections 1 and 4). This PR dissolves Tutorials and finishes the
top-level nav.

- **Tutorials redistribution.** Every remaining `docs/tutorials/` page
moves to the section it belongs to (`git mv`, table below). The
`tutorials/index.md` and `tutorials/best-practices/index.md` hub pages
are deleted, so `docs/tutorials/` no longer exists. That matters for the
folder-driven beta renderer: no stray "Tutorials" group is left.
`example-guide.md` was already deleted on `main` in #30711.
- **Duplicate Tutorials entries are dropped.** Each of these pages stays
in the sidebar at its real location: Quickstart, Image management, JFrog
Artifactory, Island browser integration, Deploy Coder on Azure with an
Application Gateway, Pre-install JetBrains IDEs, and JetBrains IDEs
air-gapped. Scale Coder was also a duplicate, already listed under
Install > Validate > Scale testing, and it stays there.
- **Istio** (`admin/integrations/istio.md`) gets its sidebar entry under
Administration > Integrations, after Island. Before this PR, only
Tutorials linked to it.
- **Nav renames.**
- About becomes **Home**, with no children; `about.yml` is renamed
`home.yml`. A third commit, `docs: title the docs landing page Home`,
changes the `docs/README.md` front matter title from About to Home and
deletes the stale HTML comment that said the first section must be
titled About.
  - Quickstart becomes **Get started**.
  - User guides becomes **Workspaces**.
- **Support** (with Support bundle) becomes a top-level section and goes
last; `about/support.yml` moves to `support.yml`.
- **Screenshots.** Nothing to do here: #31465 already deleted
`about/screenshots.md` on `main` and added its redirect.
- **Final top-level order:** Home, Get started, Install, Templates,
Workspaces, Coder Agents, AI Governance, Agent Relay, MCP server,
Administration, Reference, Support.
- Commit 2, `chore: point in-product docs links at the new docs paths`,
makes two edits outside `docs/`. You can drop it.
- `README.md`: the `docs/about#why-coder` link now points to
`docs#why-coder`.
- `cli/server.go`: the built-in PostgreSQL error message now links to
`install/server/external-database`.
- The last commit, `fix: keep docs links healthy before the release`,
reverts both of those back to the URLs that are live today
(`https://coder.com/docs/about#why-coder` and
`https://coder.com/docs/tutorials/external-database`). Both are
hardcoded, unversioned `https://coder.com/docs/...` URLs, and the new
paths 404 on the live site until a release that includes this stack
becomes the default. See "Post-release follow-up". No hand-written page
in this PR's moves had an absolute `coder.com/docs` link to a moved
page, so `docs/` needed no changes. Net, this PR changes nothing outside
`docs/`.

Stack: `docs/ia-ai-sections` (with Templates squash-merged in #31646) →
**this PR** → `docs/ia-workspaces-folder` (folder rename).

Refs: Linear DOCS-1154, DOCS-1179.

## Move map

| Old | New | Sidebar position |
| --- | --- | --- |
| `tutorials/configuring-okta.md` |
`admin/users/oidc-auth/configuring-okta.md` | Administration > Users >
OpenID Connect (last) |
| `tutorials/best-practices/organizations.md` |
`admin/users/organizations-best-practices.md` | Administration > Users,
after Organizations |
| `tutorials/best-practices/security-best-practices.md` |
`admin/security/security-best-practices.md` | Administration > Security
(last) |
| `tutorials/reverse-proxy-apache.md` |
`admin/networking/reverse-proxy-apache.md` | Administration >
Networking, before Troubleshooting |
| `tutorials/reverse-proxy-caddy.md` |
`admin/networking/reverse-proxy-caddy.md` | same |
| `tutorials/reverse-proxy-nginx.md` |
`admin/networking/reverse-proxy-nginx.md` | same |
| `tutorials/gcp-to-aws.md` | `install/operate/gcp-to-aws.md` | Install
> Operate, before Uninstall |
| `tutorials/azure-federation.md` |
`install/operate/azure-federation.md` | same |
| `tutorials/image-pull-secret.md` |
`install/operate/image-pull-secret.md` | same |
| `tutorials/postgres-ssl.md` | `install/server/postgres-ssl.md` |
Install > Install the control plane (last) |
| `tutorials/external-database.md` |
`install/server/external-database.md` | same (**deviation**, see below)
|
| `tutorials/best-practices/scale-coder.md` |
`install/validate/scale-coder.md` | unchanged: Install > Validate >
Scale testing |
| `tutorials/faqs.md` | `reference/faqs.md` | Reference (last) |
| `tutorials/persistent-shared-workspaces.md` |
`user-guides/persistent-shared-workspaces.md` | Workspaces, after Shared
workspaces |
| `tutorials/cloning-git-repositories.md` |
`user-guides/cloning-git-repositories.md` | Workspaces (end) |
| `tutorials/best-practices/speed-up-templates.md` |
`user-guides/speed-up-templates.md` | Workspaces (end) |
| `tutorials/index.md` | deleted | |
| `tutorials/best-practices/index.md` | deleted | |

All paths are relative to `docs/`. Every relative link and image path is
fixed, in moved pages and in pages that link to them, including the
`github.com/coder/coder/edit/main/docs/...` link in the FAQ page and the
link to the build timeline in
`templates/extending-templates/script-ordering.md`, which is new on
`main`.

## Redirects added

| Source | Destination |
| --- | --- |
| `/docs/tutorials/azure-federation` |
`/docs/install/operate/azure-federation` |
| `/docs/tutorials/best-practices/organizations` |
`/docs/admin/users/organizations-best-practices` |
| `/docs/tutorials/best-practices/scale-coder` |
`/docs/install/validate/scale-coder` |
| `/docs/tutorials/best-practices/security-best-practices` |
`/docs/admin/security/security-best-practices` |
| `/docs/tutorials/best-practices/speed-up-templates` |
`/docs/user-guides/speed-up-templates` |
| `/docs/tutorials/cloning-git-repositories` |
`/docs/user-guides/cloning-git-repositories` |
| `/docs/tutorials/configuring-okta` |
`/docs/admin/users/oidc-auth/configuring-okta` |
| `/docs/tutorials/external-database` |
`/docs/install/server/external-database` |
| `/docs/tutorials/faqs` | `/docs/reference/faqs` |
| `/docs/tutorials/gcp-to-aws` | `/docs/install/operate/gcp-to-aws` |
| `/docs/tutorials/image-pull-secret` |
`/docs/install/operate/image-pull-secret` |
| `/docs/tutorials/persistent-shared-workspaces` |
`/docs/user-guides/persistent-shared-workspaces` |
| `/docs/tutorials/postgres-ssl` | `/docs/install/server/postgres-ssl` |
| `/docs/tutorials/reverse-proxy-apache` |
`/docs/admin/networking/reverse-proxy-apache` |
| `/docs/tutorials/reverse-proxy-caddy` |
`/docs/admin/networking/reverse-proxy-caddy` |
| `/docs/tutorials/reverse-proxy-nginx` |
`/docs/admin/networking/reverse-proxy-nginx` |
| `/docs/tutorials/best-practices` | `/docs` (deleted hub, **please
confirm**) |
| `/docs/tutorials` | `/docs` (deleted hub, **please confirm**) |
| `/docs/about` | `/docs` |

Exact rules are used instead of a `/docs/tutorials/:path*` wildcard,
because the pages went to many different sections. The `/docs/about`
rule stays: classic coder.com adds the `/docs/about` alias only when the
first section is titled About, so after the rename that URL needs the
redirect. `/docs/about/screenshots` → `/docs` is already on `main`
(#31465), so this PR doesn't add it.

**coder.com and router static redirects:** a chain simulation of
coder.com's and the router's static rules together with this branch's
`docs/redirects.json` finds no loops or hidden pages from this PR. The
static `/docs/tutorials/...` and `/docs/about` rules there still work;
some now take two redirects. The only loops in the stack come from the
Templates move; see #31645, coder/coder.com#1201, and
coder/docs-engine#304.

## Deviations from the proposal

- **`external-database.md` goes to `install/server/`, not
`templates/`.** The page covers the control plane's PostgreSQL database,
so it sits next to `postgres-ssl.md`.
- **Dead links to the Tutorials hub.**
- `admin/index.md` linked to "Tutorials and FAQs"; it now links to the
FAQs only.
- The style guide's link-wording examples in
`docs/.style/style-guide/word-choice.md` linked "Quickstart" to
`tutorials/index.md`; they now link to `get-started/index.md`.
- **Support icon.** Top-level sections have icons, so Support gets
`info.svg`.
- **Home title.** Titling the first section Home was checked against
both renderers. Classic coder.com renders `/docs` from its own landing
component, and docs-engine maps `README.md` to the root page and already
titles it Home. `docs/README.md` stays in place, because classic serves
`/docs.md` from it and docs-preview references it. Its front matter
title is now Home, and the warning comment about the About title is
gone.
- **Other page titles not changed.** Only the sidebar titles changed.
The front matter titles of `get-started/index.md` and
`user-guides/index.md` stay as they are.
- **Proposal page count.** The proposal expected 469 pages, measured
against an older `main`. Current `main` already differs, so I report
counts below instead of matching that number.

## Open questions for Nick

1. Confirm the redirect targets for the two deleted hubs (both `/docs`).
2. `speed-up-templates.md` lands in Workspaces, as the proposal says,
but it is mostly about template build performance. Should it go to
Templates instead?
3. Confirm `external-database.md` under Install (see PR B).
4. The sidebar sources still live under `docs/manifest/`, mirroring the
new folders (`home.yml`, `support.yml`, and so on). Moving them next to
the Markdown files is the follow-up PR waiting on the naming decision
(DOCS-1154).

## Post-release follow-up

After a release that includes this stack becomes the default docs
version on coder.com, point these hardcoded URLs at the new paths. They
work today and redirect after the release.

| Current (old) URL | Post-release URL | Files |
| --- | --- | --- |
| `https://coder.com/docs/about#why-coder` |
`https://coder.com/docs#why-coder` | `README.md` |
| `https://coder.com/docs/tutorials/external-database` |
`https://coder.com/docs/install/server/external-database` |
`cli/server.go` (built-in PostgreSQL error message) |

## Validation run

- `make gen/docs-manifest`: clean diff afterward.
- `make lint/docs-manifest`, `lint/docs-redirects` (`-base
docs/ia-templates`: 34 rules OK), `lint/docs-html`, `lint/emdash`: pass.
- `pnpm check-docs` (markdownlint + table formatter): pass.
- Vale over `docs/`: the same 12 warnings and 1 error as `main`, all
pre-existing (suggestions: 645, the same as PRs A and B).
- Local relative-link check over `docs/**/*.md`: 0 unresolved.
- Pre-commit hook: `make pre-commit-light` on both docs commits, and the
full `make pre-commit` on the chore commit. `make gen` left a clean
tree.
- After the Home title commit, the full docs lint set above was re-run
and passed again (34 redirect rules OK, 0 unresolved links). Vale on
`docs/README.md` shows only its pre-existing alert.
- Restacked on the rebased `docs/ia-ai-sections` (on `main` at
`ccf5ec74ae`). After the restack, `make gen/docs-manifest` (clean),
`lint/docs-manifest`, `lint/docs-redirects` (34 rules OK),
`lint/docs-html`, `lint/emdash`, `pnpm check-docs`, and the
relative-link and anchor check over the changed pages pass.
- **Link health (fix commit):**
- linkspector 0.5.6 with `.github/.linkspector.yml` over all of `docs/`,
like the weekly docs job, run locally.
- `origin/main`: 0 errors. This branch before the fix (`5fe2b627df`, on
the pre-fix `docs/ia-ai-sections`): the same 6
`https://coder.com/docs/<new path>` 404s as #31645, plus a transient Red
Hat URL failure in `install/server/openshift.md`. That URL is unchanged
from `main`, and it passed on reruns. After rebasing onto the fixed
`docs/ia-ai-sections` and adding this fix (`c664641e1e`): 0 errors.
Nothing is new compared with `main`.
- After the fix: `make gen/docs-manifest` (clean), `lint/docs-manifest`,
`lint/docs-redirects` (34 rules OK against `docs/ia-ai-sections`),
`lint/docs-html`, `lint/emdash`, `pnpm check-docs`, and the
relative-link check (0 unresolved) pass. The full `make pre-commit`
passed on the commit.
- Page counts across the stack:

| | `main` | after A | after B | after C |
| --- | --- | --- | --- | --- |
| `docs/**/*.md` (excl. `.style`) | 490 | 487 | 487 | 485 |
| `manifest.json` routes | 495 | 492 | 492 | 482 |

The 10 routes removed in C are the 2 Tutorials hubs, 7 duplicate
Tutorials entries, and the duplicate Scale Coder entry. The Istio entry
moved, so it nets to zero.
- **Skipped:** the docs-engine sync check, which was not available in
this environment.

<details>
<summary>Implementation notes</summary>

- Rebuilt on the new `docs/ia-templates`, which is based on `main` at
`9839406ff7` (2026-11-02). After #31646 squash-merged PR B into
`docs/ia-ai-sections`, this branch was rebased onto it with `git rebase
--onto`; the tree didn't change. It was rebased again onto
`docs/ia-ai-sections` after #31645's link-health fix commit
(`def074caab`), which applied cleanly.
- Restacked on 2026-11-03 onto `docs/ia-ai-sections` at `4c356c6314`,
after #31645 was rebased onto `main` at `ccf5ec74ae`. The restack
applied cleanly. Folded into the docs commit: the links between
`shared-workspaces.md` and `persistent-shared-workspaces.md` that `main`
added in #31152 now resolve from the moved page. `git range-diff`
against the previous head (`c664641e1e`) shows only those changes and
the sidebar entry `main` added for Bring your own MCP servers.
- The same one-shot move script as PRs A and B did the move and link
pass from a clean tree. Run on the old base, it reproduced the old
commit except for the three hand edits listed under Deviations (dead
Tutorials hub links), which were reapplied by hand.
- The sidebar changes were applied with a three-way merge of each YAML
file from the earlier version of this branch onto the current files, so
entries added on `main` since then (for example Nix(OS) under
Integrations) stay in place.
- Changes from the earlier version of this branch: the Screenshots page
and its redirect are gone from this PR, because #31465 did both on
`main`. `admin/index.md` was reworded on `main`, and the Tutorials hub
link was removed from the new wording. One more page link is fixed
(`script-ordering.md`).

</details>

<details>
<summary>CI flake on <code>70232dbbfb</code></summary>

The `fmt` job failed because GitHub canceled the step on the Depot
runner, before any formatting ran. A rerun of the failed jobs passed.

</details>

---------

Co-authored-by: coder[bot] <137810501+coder[bot]@users.noreply.github.com>
Co-authored-by: Nick Vigilante <nick.vigilante@coder.com>
2026-11-04 17:30:25 -05:00

6.4 KiB

title
title
Configure control plane access

The control plane's primary configuration is done via environment variables. For a full list of the options, run coder server --help or see our CLI documentation.

Tip

Need to look up an exact environment variable, CLI flag, or YAML key for a setting? See the configuration reference for a searchable list of every option.

Access URL

CODER_ACCESS_URL is required if you are not using the tunnel. Set this to the external URL that users and workspaces use to connect to Coder (for example, https://coder.example.com). This should not be localhost.

Access URL should be an external IP address or domain with DNS records pointing to Coder.

Tunnel

If an access URL is not specified, Coder will create a publicly accessible URL to reverse proxy your deployment for simple setup.

Address

You can change which port(s) Coder listens on.

# Listen on port 80
export CODER_HTTP_ADDRESS=0.0.0.0:80

# Enable TLS and listen on port 443)
export CODER_TLS_ENABLE=true
export CODER_TLS_ADDRESS=0.0.0.0:443

## Redirect from HTTP to HTTPS
export CODER_REDIRECT_TO_ACCESS_URL=true

# Start the control plane
coder server

Wildcard access URL

Tip

Learn more about the importance and benefits of wildcard access URLs

CODER_WILDCARD_ACCESS_URL is necessary for port forwarding via the dashboard or running coder_apps on an absolute path. Set it to a wildcard hostname that resolves to Coder, such as *.coder.example.com or *-coder.example.com. The suffix form creates application hostnames such as 8080--main--myworkspace--john-coder.example.com. It requires a DNS record and TLS certificate for *.example.com.

Note

We do not recommend using a top-level-domain for Coder wildcard access (for example *.workspaces), even on private networks with split-DNS. Some browsers consider these "public" domains and will refuse Coder's cookies, which are vital to the proper operation of this feature.

If you are providing TLS certificates directly to the control plane, either

  1. Use a single certificate and key for both the root and wildcard domains.

  2. Configure multiple certificates and keys via coder.tls.secretNames in the Helm Chart, or --tls-cert-file and --tls-key-file command line options.

    These options both take a comma separated list of files. List certificates and their respective keys in the same order.

After you enable the wildcard access URL, you should disable path-based apps for security.

TLS & Reverse Proxy

The control plane can directly use TLS certificates with CODER_TLS_ENABLE and accompanying configuration flags. However, Coder can also run behind a reverse-proxy to terminate TLS certificates from LetsEncrypt.

Kubernetes TLS configuration

Below are the steps to configure Coder to terminate TLS when running on Kubernetes. You must have the certificate .key and .crt files in your working directory prior to step 1.

  1. Create the TLS secret in your Kubernetes cluster

    kubectl create secret tls coder-tls -n <coder-namespace> --key="tls.key" --cert="tls.crt"
    

    You can use a single certificate for the both the access URL and wildcard access URL. The certificate Common Name (CN) must match the wildcard domain, such as *.example.coder.com.

  2. Reference the TLS secret in your Coder Helm chart values

    coder:
      tls:
        secretNames:
          - coder-tls
    
      # Alternatively, if you use an Ingress controller to terminate TLS,
      # set the following values:
      ingress:
        enable: true
        tls:
          enable: true
          secretName: coder-tls
          wildcardSecretName: coder-tls
    

PostgreSQL Database

Coder uses a PostgreSQL database to store users, workspace metadata, and other deployment information. Use CODER_PG_CONNECTION_URL to set the database that Coder connects to. If unset, PostgreSQL binaries will be downloaded from Maven (https://repo1.maven.org/maven2) and store all data in the config root.

Note

Postgres 13 is the minimum supported version.

If you are using the built-in PostgreSQL deployment and need to use psql (aka the PostgreSQL interactive terminal), output the connection URL with the following command:

$ coder server postgres-builtin-url
psql "postgres://coder@localhost:49627/coder?sslmode=disable&password=feU...yI1"

Migrate from the built-in database to an external database

To migrate from the built-in database to an external database, follow these steps:

  1. Stop your Coder deployment.
  2. Run coder server postgres-builtin-serve in a background terminal.
  3. Run coder server postgres-builtin-url and copy its output command.
  4. Run pg_dump <built-in-connection-string> > coder.sql to dump the internal database to a file.
  5. Restore that content to an external database with psql <external-connection-string> < coder.sql.
  6. Start your Coder deployment with CODER_PG_CONNECTION_URL=<external-connection-string>.

Configure Coder behind a proxy

To configure Coder behind a corporate proxy, set the environment variables HTTP_PROXY and HTTPS_PROXY. Be sure to restart the control plane. Lowercase values (for example, http_proxy) are also respected in this case.

Continue your setup with external authentication

Coder supports external authentication via OAuth2.0. This allows enabling integrations with Git providers, such as GitHub, GitLab, and Bitbucket.

External authentication can also be used to integrate with external services like JFrog Artifactory and others.

Refer to the external authentication section for more information.

Up Next