Files
coder/docs/tutorials/reverse-proxy-apache.md
T
Nick Vigilante 81c40579dc feat: enable Coder.StepLength Vale rule (#30791)
Adds `Coder.StepLength`, a Vale `script` rule for [Keep steps
short](https://github.com/coder/coder/blob/main/docs/.style/style-guide/procedural-writing.md#keep-steps-short).
It flags an ordered-list step whose instruction, the step's first
paragraph, has more than 20 words, counted as [How to count
words](https://github.com/coder/coder/blob/main/docs/.style/style-guide/voice-and-tone.md#how-to-count-words)
describes.
Paragraphs below the instruction explain the step and aren't counted.

- Severity: `warning`.
- Scope: `docs/**` except `docs/.style/style-guide/**`.
- Baseline: 124 findings in 60 hand-written files.
The cleanup shortens each long instruction, moves its explanation into
one paragraph below it, or splits a step that holds several actions.
After cleanup `vale docs/` reports 0 `Coder.StepLength` findings, and
the other rules report no new findings on the changed files.
- The guide section now says the limit covers the instruction, and that
one action or one explanation must not be broken across paragraphs to
meet it.
- Generated pages (`docs/reference/{api,cli,agent-api}`,
`configuration-reference.md`, `prometheus.md`): no findings, so no
`.vale.ini` exclusion is needed.

Linear: DOCS-1272

<details><summary>Decision log</summary>

**Review change (Ian's review)**

- The first version limited every paragraph of a step to 20 words.
The cleanup for it chopped explanations into several short paragraphs,
which made steps harder to read and sometimes changed their meaning.
- The rule now counts only the first paragraph segment of each step.
The content files were reset to `main` and the cleanup was redone
against the narrower rule.
- Cleanup preferences, in order: shorten the instruction; keep a short
instruction and put the explanation, with its original wording, in one
paragraph below it; split a step into one step for each action; for
descriptive lists (such as "How it works"), keep each item one
statement.
- `docs/admin/users/oidc-auth/microsoft.md` keeps the split into
separate steps, with Ian's wording suggestions applied.
"click" became "select" in step 16 because `Coder.SelectClick` flags it.

**Rule shape**

- A `script` rule (Tengo) with `scope: raw`, because the count depends
on Markdown structure that per-paragraph scopes hide.
- A step is an ordered-list item with a `1.` or `1)` marker.
  A nested ordered item is its own step.
  Bullets, even under a step, are not steps.
- The instruction ends at a blank line, a fence, a nested list, a table
row, a blockquote, block-level HTML, or an explicit hard break (`<br>`,
a trailing backslash, or two trailing spaces).
- Fenced code blocks, HTML comments, tables, images, and nested bullets
add no words.
- CRLF: `\r` counts as whitespace, and offsets come from the raw text.

**Counting approximations (also in the rule header)**

- A code span and a `**bold**` or `__bold__` span are one word each.
- Words split on whitespace, so a hyphenated compound and
`30&nbsp;seconds` are one word.
- Link text counts word by word, destinations are skipped, images add no
words, and `<https://...>` autolinks are one word.
- A token with no letter or digit, such as the `>` in `**A** > **B**`,
is not a word.
- Tengo indexes strings by rune but measures them in bytes, so the
script rewrites each non-ASCII rune to ASCII of the same byte length
first.

**Tests** (fixtures under `/tmp/sltest/`, not committed; run with the
repo `.vale.ini`, LF and CRLF)

- Flagged: a long instruction, a short action and a long result in one
paragraph, a long nested ordered step.
- Not flagged: a long paragraph below a short instruction, text after a
`<br>` hard break, a long paragraph after a code block, a long nested
bullet.
- LF and CRLF output is identical.
- Pre-commit hooks (`fmt/markdown`, `lint/markdown`, `lint/emdash`,
`lint/style-claims`, `lint/typos`) pass.
- Not run on Windows or macOS.
The rule is plain text processing, and the CRLF cases simulate Windows
line endings on Linux.

</details>

*Generated by [Coder Agents](https://coder.com/docs/ai-coder/agents) on
behalf of @nickvigilante.*
2026-10-26 20:43:38 -04:00

163 lines
4.4 KiB
Markdown

---
title: How to use Apache as a reverse proxy with Let's Encrypt
---
## Requirements
1. Start a Coder deployment and be sure to set the following [configuration values](../admin/setup/index.md):
```dotenv
CODER_HTTP_ADDRESS=127.0.0.1:3000
CODER_ACCESS_URL=https://coder.example.com
CODER_WILDCARD_ACCESS_URL=*coder.example.com
```
Throughout the guide, be sure to replace `coder.example.com` with the domain you intend to use with Coder.
2. Configure your DNS provider to point your coder.example.com and `*.coder.example.com` to your server's public IP address.
> For example, to use `coder.example.com` as your subdomain, configure `coder.example.com` and `*.coder.example.com` to point to your server's public ip.
> This can be done by adding A records in your DNS provider's dashboard.
3. Install Apache (assuming you're on Debian/Ubuntu):
```sh
sudo apt install apache2
```
4. Enable the following Apache modules:
```sh
sudo a2enmod proxy
sudo a2enmod proxy_http
sudo a2enmod ssl
sudo a2enmod rewrite
```
5. Stop Apache service and disable default site:
```sh
sudo a2dissite 000-default.conf
sudo systemctl stop apache2
```
## Install and configure LetsEncrypt Certbot
1. Install LetsEncrypt Certbot: Refer to the [CertBot documentation](https://certbot.eff.org/instructions?ws=apache&os=ubuntufocal&tab=wildcard).
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](https://eff-certbot.readthedocs.io/en/stable/using.html#dns-plugins).
1. Create an API token for the DNS provider you're using, for example, [CloudFlare](https://developers.cloudflare.com/fundamentals/api/get-started/create-token) with the following permissions:
- Zone - DNS - Edit
2. Create a file in `.secrets/certbot/cloudflare.ini` with the following content:
```ini
dns_cloudflare_api_token = YOUR_API_TOKEN
```
```sh
mkdir -p ~/.secrets/certbot
touch ~/.secrets/certbot/cloudflare.ini
nano ~/.secrets/certbot/cloudflare.ini
```
3. Set the correct permissions:
```sh
sudo chmod 600 ~/.secrets/certbot/cloudflare.ini
```
## Create the certificate
1. Create the wildcard certificate:
```sh
sudo certbot certonly --dns-cloudflare --dns-cloudflare-credentials ~/.secrets/certbot/cloudflare.ini -d coder.example.com -d *.coder.example.com
```
## Configure Apache
This example assumes Coder is running locally on `127.0.0.1:3000` and that you're using `coder.example.com` as your subdomain.
1. Create Apache configuration for Coder:
```sh
sudo nano /etc/apache2/sites-available/coder.conf
```
2. Add the following content:
```apache
# Redirect HTTP to HTTPS
<VirtualHost *:80>
ServerName coder.example.com
ServerAlias *.coder.example.com
Redirect permanent / https://coder.example.com/
</VirtualHost>
<VirtualHost *:443>
ServerName coder.example.com
ServerAlias *.coder.example.com
ErrorLog ${APACHE_LOG_DIR}/error.log
CustomLog ${APACHE_LOG_DIR}/access.log combined
ProxyPass / http://127.0.0.1:3000/ upgrade=any # required for websockets
ProxyPassReverse / http://127.0.0.1:3000/
ProxyRequests Off
ProxyPreserveHost On
RewriteEngine On
# Websockets are required for workspace connectivity
RewriteCond %{HTTP:Connection} Upgrade [NC]
RewriteCond %{HTTP:Upgrade} websocket [NC]
RewriteRule /(.*) ws://127.0.0.1:3000/$1 [P,L]
SSLCertificateFile /etc/letsencrypt/live/coder.example.com/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/coder.example.com/privkey.pem
</VirtualHost>
```
> Do not forget to change: `coder.example.com` by your (sub)domain
3. Enable the site:
```sh
sudo a2ensite coder.conf
```
4. Restart Apache:
```sh
sudo systemctl restart apache2
```
## Refresh certificates automatically
1. Create a new file in `/etc/cron.weekly`:
```sh
sudo touch /etc/cron.weekly/certbot
```
2. Make it executable:
```sh
sudo chmod +x /etc/cron.weekly/certbot
```
3. And add this code:
```sh
#!/bin/sh
sudo certbot renew -q
```
And that's it, you should now be able to access Coder at your sub(domain), for example, `https://coder.example.com`.