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 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.*
163 lines
4.4 KiB
Markdown
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`.
|