Builds on #30782, which is merged; the branch now merges `main`. Adds `Coder.LatinAbbreviations`, a Vale rule that enforces [Latin abbreviations](https://github.com/coder/coder/blob/main/docs/.style/style-guide/accessibility-and-inclusion.md#latin-abbreviations). - Suggests "for example", "that is", and "and so on" for `e.g.`, `i.e.`, and `etc.`, including `eg.`, `ie.`, and a missing final period (`e.g`). - Severity: `suggestion`. Scope: `docs/**` except `docs/.style/style-guide/**`, limited to paragraphs, lists, headings, and blockquotes. Table cells and code are skipped. - Baseline: 170 findings in 91 files. The brief estimated 148. - Cleanup: 153 findings fixed across 81 hand-written pages, 0 left in linted pages. The count is lower than the original 158 because other PRs on `main` already rewrote or removed some of the lines, and `parameters.md` was deleted on `main`. - `vs.` and `et al.` aren't flagged. Commits: 1. `docs(docs): use English forms of Latin abbreviations` 2. `feat(docs/.style): enable Coder.LatinAbbreviations Vale rule` Generated pages: `.vale.ini` skips `docs/reference/{api,cli}/*.md` and `docs/admin/setup/configuration-reference.md` for this rule, as it does for `Coder.UnitSpacing`. Their prose comes from CLI flag help text and Swagger comments in Go source, and `make gen` rewrites them, so a hand edit fails the `gen` check (an earlier revision of this PR edited `configuration-reference.md` and failed `gen` for that reason). Cleaning them means editing Go and regenerating the help golden files and API docs, which is left for a follow-up. Linear: DOCS-450 <details> <summary>Decision log</summary> - `extends: substitution`, so the message names the replacement: "Consider 'for example' instead of 'e.g.'". - `scope: [paragraph, list, heading, blockquote]`. The single scope `paragraph` skips list items, blockquotes, and headings, so all four are listed. Table cells have their own scope and stay excluded. - Explicit `[Ee]` and `[Ii]` classes with `ignorecase: false`, so sentence-initial `E.g.,` still matches but the browser name `IE.` doesn't. - `eg.` and `ie.` require the trailing period so ordinary words and file extensions stay quiet. - Cleanup rules, applied by script and then reviewed line by line: - `e.g.` and `i.e.` become "for example," and "that is," (capitalized at the start of a sentence), with a comma added when the original had none. - `etc.` becomes "and so on", with the sentence-ending period kept when `etc.` closed the sentence. - Lines inside table rows, fenced blocks, and code spans are untouched, so are the style guide and the generated pages. - Hard-wrapped lines keep their wrapping, and CRLF files keep CRLF. - The rest of the Vale output is unchanged: the per-rule counts for every other rule match the pre-cleanup run. Test cases (fixtures under `/tmp/latin-test/`, not committed), run with LF and CRLF line endings: - Flagged (15 each): `e.g.,` in a paragraph, `i.e.,`, `etc.` at the end of a sentence and before a comma, `eg.`, `ie.`, `e.g` and `i.e` without the final period, `E.g.,`, `I.e.,`, `Etc.`, a blockquote, a list item, a numbered item, and a heading. - Not flagged: a table row with `e.g.,`, `i.e.,`, and `etc.`, code spans, a fenced block, "for example", "that is", "and so on", `IE.`, `genre`, `series`, `egg`, `tie`, `etcetera`, `vs.`, `et al.`. - Known edge case: a path-like token such as `path/i.e/x` outside code matches. It doesn't occur in the corpus. Checks: - `vale --output=line docs/`: 0 `Coder.LatinAbbreviations` findings. - `go run ./scripts/styleclaims` passes. - The pre-commit-light hook passes on both commits. </details> *Generated by [Coder Agents](https://coder.com/docs/ai-coder/agents) on behalf of @nickvigilante.*
8.7 KiB
title
| title |
|---|
| Caddy |
This is an example configuration of how to use Coder with caddy. To use Caddy to generate TLS certificates, you'll need a domain name that resolves to your Caddy server.
Get started
With docker compose
-
Create a
compose.yamlfile and add the following:services: coder: image: ghcr.io/coder/coder:${CODER_VERSION:-latest} environment: CODER_PG_CONNECTION_URL: "postgresql://${POSTGRES_USER:-username}:${POSTGRES_PASSWORD:-password}@database/${POSTGRES_DB:-coder}?sslmode=disable" CODER_HTTP_ADDRESS: "0.0.0.0:7080" # You'll need to set CODER_ACCESS_URL to an IP or domain # that workspaces can reach. This cannot be localhost # or 127.0.0.1 for non-Docker templates! CODER_ACCESS_URL: "${CODER_ACCESS_URL}" # Optional) Enable wildcard apps/dashboard port forwarding CODER_WILDCARD_ACCESS_URL: "${CODER_WILDCARD_ACCESS_URL}" # If the coder user does not have write permissions on # the docker socket, you can uncomment the following # lines and set the group ID to one that has write # permissions on the docker socket. #group_add: # - "998" # docker group on host volumes: - /var/run/docker.sock:/var/run/docker.sock depends_on: database: condition: service_healthy database: image: "postgres:17" ports: - "5432:5432" environment: POSTGRES_USER: ${POSTGRES_USER:-username} # The PostgreSQL user (useful to connect to the database) POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-password} # The PostgreSQL password (useful to connect to the database) POSTGRES_DB: ${POSTGRES_DB:-coder} # The PostgreSQL default database (automatically created at first launch) volumes: - coder_data:/var/lib/postgresql/data # Use "docker volume rm coder_coder_data" to reset Coder healthcheck: test: [ "CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-username} -d ${POSTGRES_DB:-coder}", ] interval: 5s timeout: 5s retries: 5 caddy: image: caddy:2.6.2 ports: - "80:80" - "443:443" - "443:443/udp" volumes: - $PWD/Caddyfile:/etc/caddy/Caddyfile - caddy_data:/data - caddy_config:/config volumes: coder_data: caddy_data: caddy_config: -
Create a
Caddyfileand add the following:{ on_demand_tls { ask http://example.com } } coder.example.com, *.coder.example.com { reverse_proxy coder:7080 tls { on_demand issuer acme { email email@example.com } } }Here;
coder:7080is the address of the Coder container on the Docker network.coder.example.comis the domain name you're using for Coder.*.coder.example.comis the domain name for wildcard apps, commonly used for dashboard port forwarding. This is optional and can be removed.email@example.com: Email to request certificates from LetsEncrypt/ZeroSSL (does not have to be Coder admin email)ask http://example.com: Change this to a URL you control that validates the requested hostname before Caddy requests a certificate for it. See this discussion for a reference implementation.
-
Start Coder. Set
CODER_ACCESS_URLandCODER_WILDCARD_ACCESS_URLto the domain you're using in your Caddyfile.export CODER_ACCESS_URL=https://coder.example.com export CODER_WILDCARD_ACCESS_URL=*.coder.example.com docker compose up -d # Run on startup
Standalone
-
If you haven't already, install Coder
-
Install Caddy Server
-
Copy our sample
Caddyfileand change the following values:{ on_demand_tls { ask http://example.com } } coder.example.com, *.coder.example.com { reverse_proxy coder:7080 }If you're installed Caddy as a system package, update the default Caddyfile with
vim /etc/caddy/Caddyfileemail@example.com: Email to request certificates from LetsEncrypt/ZeroSSL (does not have to be Coder admin email)coder.example.com: Domain name you're using for Coder.*.coder.example.com: Domain name for wildcard apps, commonly used for dashboard port forwarding. This is optional and can be removed.localhost:3000: Address Coder is running on. Modify this if you changedCODER_HTTP_ADDRESSin the Coder configuration.ask http://example.com: Change this to a URL you control that validates the requested hostname before Caddy requests a certificate for it. See this discussion for a reference implementation.
-
Configure Coder and change the following values:
CODER_ACCESS_URL: root domain (for example,https://coder.example.com)CODER_WILDCARD_ACCESS_URL: wildcard domain (for example,*.example.com).
-
Start the Caddy server:
If you're keeping Caddy running via a system service:
sudo systemctl restart caddyOr run a standalone server:
caddy run -
Optionally, use ufw or another firewall to disable external traffic outside of Caddy.
# Check status of UncomplicatedFirewall sudo ufw status # Allow SSH sudo ufw allow 22 # Allow HTTP, HTTPS (Caddy) sudo ufw allow 80 sudo ufw allow 443 # Deny direct access to Coder server sudo ufw deny 3000 # Enable UncomplicatedFirewall sudo ufw enable -
Navigate to your Coder URL! A TLS certificate should be auto-generated on your first visit.
Generate wildcard certificates
By default, this configuration uses Caddy's on-demand TLS to generate a certificate for each subdomain (for example, app1.coder.example.com, app2.coder.example.com).
When users visit new subdomains, such as accessing ports on a workspace, the request will take an additional 5-30 seconds since a new certificate is being generated.
For production deployments, we recommend configuring Caddy to generate a wildcard certificate, which requires an explicit DNS challenge and additional Caddy modules.
-
Install a custom Caddy build that includes the caddy-dns module for your DNS provider (for example, CloudFlare, Route53).
-
Docker: Build an custom Caddy image with the module for your DNS provider. Be sure to reference the new image in the
compose.yaml. -
Standalone: Download a custom Caddy build with the module for your DNS provider. If you're using Debian/Ubuntu, you can configure the Caddy package to use the new build.
-
-
Edit your
Caddyfileand add the necessary credentials/API tokens to solve the DNS challenge for wildcard certificates.For example, for AWS Route53:
tls { - on_demand - issuer acme { - email email@example.com - } + dns route53 { + max_retries 10 + aws_profile "real-profile" + access_key_id "AKI..." + secret_access_key "wJa..." + token "TOKEN..." + region "us-east-1" + } }Configuration reference from caddy-dns/route53.
And for CloudFlare:
Generate a token with the following permissions:
- Zone:Zone:Edit
tls { - on_demand - issuer acme { - email email@example.com - } + dns cloudflare CLOUDFLARE_API_TOKEN }Configuration reference from caddy-dns/cloudflare.