> [!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>
4.6 KiB
title
| title |
|---|
| How to use NGINX as a reverse proxy with Let's Encrypt |
Requirements
-
Start a Coder deployment and be sure to set the following configuration values:
CODER_HTTP_ADDRESS=127.0.0.1:3000 CODER_ACCESS_URL=https://coder.example.com CODER_WILDCARD_ACCESS_URL=*.coder.example.comThroughout the guide, be sure to replace
coder.example.comwith the domain you intend to use with Coder. -
Configure your DNS provider to point your coder.example.com and
*.coder.example.comto your server's public IP address.For example, to use
coder.example.comas your subdomain, configurecoder.example.comand*.coder.example.comto point to your server's public ip. This can be done by adding A records in your DNS provider's dashboard. -
Install NGINX (assuming you're on Debian/Ubuntu):
sudo apt install nginx -
Stop NGINX service:
sudo systemctl stop nginx
Add the Coder deployment subdomain
This example assumes Coder is running locally on 127.0.0.1:3000 and that you're using coder.example.com as your subdomain.
-
Create NGINX configuration for this app:
sudo touch /etc/nginx/sites-available/coder.example.com -
Activate this file:
sudo ln -s /etc/nginx/sites-available/coder.example.com /etc/nginx/sites-enabled/coder.example.com
Install and configure LetsEncrypt Certbot
-
Install LetsEncrypt Certbot: Refer to the CertBot documentation.
Be sure to pick the wildcard tab and select your DNS provider for instructions to install the necessary DNS plugin.
Create DNS provider credentials
This example assumes you're using CloudFlare as your DNS provider. For other providers, refer to the CertBot documentation.
-
Create an API token for the DNS provider you're using, for example, CloudFlare with the following permissions:
- Zone - DNS - Edit
-
Create a file in
.secrets/certbot/cloudflare.iniwith the following content:dns_cloudflare_api_token = YOUR_API_TOKENmkdir -p ~/.secrets/certbot touch ~/.secrets/certbot/cloudflare.ini nano ~/.secrets/certbot/cloudflare.ini -
Set the correct permissions:
sudo chmod 600 ~/.secrets/certbot/cloudflare.ini
Create the certificate
-
Create the wildcard certificate:
sudo certbot certonly --dns-cloudflare --dns-cloudflare-credentials ~/.secrets/certbot/cloudflare.ini -d coder.example.com -d *.coder.example.com
Configure nginx
-
Edit the file with:
sudo nano /etc/nginx/sites-available/coder.example.com -
Add the following content:
server { server_name coder.example.com *.coder.example.com; # HTTP configuration listen 80; listen [::]:80; # HTTP to HTTPS if ($scheme != "https") { return 301 https://$host$request_uri; } # HTTPS configuration listen [::]:443 ssl ipv6only=on; listen 443 ssl; ssl_certificate /etc/letsencrypt/live/coder.example.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/coder.example.com/privkey.pem; location / { proxy_pass http://127.0.0.1:3000; # Change this to your coder deployment port default is 3000 proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; add_header Strict-Transport-Security "max-age=15552000; includeSubDomains" always; } }Do not forget to change:
coder.example.comby your (sub)domain -
Test the configuration:
sudo nginx -t
Refresh certificates automatically
-
Create a new file in
/etc/cron.weekly:sudo touch /etc/cron.weekly/certbot -
Make it executable:
sudo chmod +x /etc/cron.weekly/certbot -
And add this code:
#!/bin/sh sudo certbot renew -q
Restart NGINX
sudo systemctl restart nginx
And that's it, you should now be able to access Coder at your sub(domain), for example, https://coder.example.com.