Files
coder/docs/tutorials/reverse-proxy-caddy.md
T
Nick Vigilante 21471da74c feat: enable Coder.Semicolons Vale rule (#30787)
Depends on #30782.

Adds `Coder.Semicolons`, a Vale rule that flags a semicolon in prose.
It enforces [No semicolons in
prose](https://github.com/coder/coder/blob/main/docs/.style/style-guide/capitalization-and-punctuation.md#no-semicolons-in-prose).

- Severity: `warning`.
- Scope: paragraphs, list items, headings, and blockquotes in `docs/**`
except `docs/.style/style-guide/**`.
  Table cells, code spans, and code blocks keep their semicolons.
- Baseline: 137 findings.
The cleanup commit fixes 112 of them across 61 files by splitting
sentences, or by using a comma or a connecting word where a split reads
badly.
- Excluded in `.vale.ini`: `docs/reference/{api,cli}/*.md` and
`docs/admin/setup/configuration-reference.md`.
Their text is generated from Go source (CLI flag help, Swagger
comments), and 25 findings live there.
Fixing them means editing Go and regenerating, so I used a commented
exclusion like `Coder.UnitSpacing` does.
  Say so if you prefer the Go fix.
- Result: `vale --output=line docs/` reports 0 `Coder.Semicolons`
findings outside the style guide.
- Three headings lost a semicolon, so their anchors changed.
I updated the links in `docs/.style/` and in `.claude/`
(`DOCS_STYLE_GUIDE.md`, the `write-docs` and `doc-check` skills).

Linear: DOCS-1261

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

- Scope list is `paragraph`, `list`, `heading`, `blockquote`. Without
`blockquote`, a semicolon in a `>` quote goes unreported, which I
checked.
Table cells are outside those scopes, so they stay exempt without extra
config.
- Token is `(?<!TL);(?!DR)`. `TL;DR` in `telemetry.md` is an
abbreviation, not punctuation.
- `&nbsp;` entities and `style="a: b;"` attributes don't match. Vale can
report a real semicolon on the wrong line of a paragraph that contains
an entity or raw HTML (for example, `modules.md:69` pointed at a
semicolon on line 71), so cleanup used a paragraph-wide search instead
of trusting reported lines.
- A semicolon inside a fenced block in a blockquote
(`ai-gateway/monitoring.md:105`, a YAML comment) isn't reported and
stays.
- Cleanup default: `; x` becomes `. X`, then I reviewed the diff and
hand-fixed list fragments, parentheticals, and headings.
Each new sentence sits on its own line, outside table cells. The
hand-written part of `prometheus.md` is also reformatted to one sentence
per line.
- Heading rewrites: `Verify against the code and document exact values`,
`Evidence justifies a claim and does not belong in the claim`, `STUN
returned different addresses and you may be behind a hard NAT`.
- `prometheus.md` is in the generated-page exclusion for
`Coder.UnitSpacing` but not here. Its semicolon was in hand-written
prose, so I fixed it.
- Enable commit updates the footer, the checks table (scope text matches
`.vale.ini`), the coverage counts (Capitalization and punctuation 3/7 to
4/6, total 20 to 21 tool-checked and 25 to 24 planned), and the "What
the tooling checks" counts.

Tests (fixtures in `/tmp`, not committed), each run with LF and CRLF
files:

- Flagged: paragraph, list item, ordered list item, heading, blockquote.
- Not flagged: table cell, code span, fenced block, `&nbsp;` and
`&amp;`, an HTML `style` attribute, and `TL;DR`.
- `go run ./scripts/styleclaims`, `make lint/emdash`, and the pre-commit
hook (markdown, typos, style-claims) pass.

</details>

*Generated by [Coder Agents](https://coder.com/docs/ai-coder/agents) on
behalf of @nickvigilante.*
2026-10-27 16:44:17 +00:00

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

  1. Install Docker and Docker Compose

  2. Create a compose.yaml file 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:
    
  3. Create a Caddyfile and 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:7080 is the address of the Coder container on the Docker network.
    • coder.example.com is the domain name you're using for Coder.
    • *.coder.example.com is 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.
  4. Start Coder. Set CODER_ACCESS_URL and CODER_WILDCARD_ACCESS_URL to 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

  1. If you haven't already, install Coder

  2. Install Caddy Server

  3. Copy our sample Caddyfile and 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/Caddyfile

    • email@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 changed CODER_HTTP_ADDRESS in 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.
  4. 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).
  5. Start the Caddy server:

    If you're keeping Caddy running via a system service:

    sudo systemctl restart caddy
    

    Or run a standalone server:

    caddy run
    
  6. 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
    
  7. 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.

  1. Install a custom Caddy build that includes the caddy-dns module for your DNS provider (for example, CloudFlare, Route53).

  2. Edit your Caddyfile and 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.