docs: add Caddy+LetsEncrypt TLS example (coder#4585)

bpmct · web-flow · commit 12cb4f1eb34e · 2022-10-19T07:20:11.000-05:00
* structure

* docs: add Caddy+LetsEncrypt TLS example
diff --git a/docs/admin/configure.md b/docs/admin/configure.md
@@ -23,6 +23,12 @@ subdomain that resolves to Coder (e.g. `*.coder.example.com`).
 > If you are providing TLS certificates directly to the Coder server, you must use a single certificate for the
 > root and wildcard domains. Multi-certificate support [is planned](https://github.com/coder/coder/pull/4150).
 
+## TLS Certificates
+
+The Coder server can directly use TLS certificates with `CODER_TLS_ENABLE` and accompanying configuration flags. However, Coder can also run behind a reverse-proxy to terminate TLS certificates from LetsEncrypt, for example.
+
+- Example: [Run Coder with Caddy and LetsEncrypt](https://github.com/coder/coder/tree/main/examples/web-server/caddy)
+
 ## PostgreSQL Database
 
 Coder uses a PostgreSQL database to store users, workspace metadata, and other deployment information.
diff --git a/examples/web-server/caddy/Caddyfile b/examples/web-server/caddy/Caddyfile
@@ -0,0 +1,9 @@
+coder.example.com, *.coder.example.com {
+  reverse_proxy localhost:3000
+  tls {
+    on_demand
+    issuer acme {
+      email email@example.com
+    }
+  }
+}
diff --git a/examples/web-server/caddy/README.md b/examples/web-server/caddy/README.md
@@ -0,0 +1,127 @@
+# Caddy
+
+This is an example configuration of how to use Coder with [caddy](https://caddyserver.com/docs). To use Caddy to generate TLS certificates, you'll need a domain name that resolves to your Caddy server.
+
+## Getting started
+
+### With docker-compose
+
+1. [Install Docker](https://docs.docker.com/engine/install/) and [Docker Compose](https://docs.docker.com/compose/install/)
+
+1. Start with our example configuration
+
+   ```sh
+   # Create a project folder
+   cd $HOME
+   mkdir coder-with-caddy
+   cd coder-with-caddy
+
+   # Clone coder/coder and copy the Caddy example
+   git clone https://github.com/coder/coder /tmp/coder
+   mv /tmp/coder/examples/web-server/caddy $(pwd)
+   ```
+
+1. Modify the [Caddyfile](./Caddyfile) and change the following values:
+
+   - `localhost:3000`: Change to `coder:7080` (Coder container on Docker network)
+   - `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](https://coder.com/docs/coder-oss/latest/networking/port-forwarding#dashboard). This is optional and can be removed.
+
+1. Start Coder. Set `CODER_ACCESS_URL` and `CODER_WILDCARD_ACCESS_URL` to the domain you're using in your Caddyfile.
+
+   ```sh
+   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](https://coder.com/docs/coder-oss/latest/install)
+
+1. Install [Caddy Server](https://caddyserver.com/docs/install)
+
+1. Copy our sample [Caddyfile](./Caddyfile) and change the following values:
+
+   > 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](https://coder.com/docs/coder-oss/latest/networking/port-forwarding#dashboard). This is optional and can be removed.
+   - `localhost:3000`: Address Coder is running on. Modify this if you changed `CODER_ADDRESS` in the Coder configuration.
+
+1. [Configure Coder](https://coder.com/docs/coder-oss/latest/admin/configure) and change the following values:
+
+   - `CODER_ACCESS_URL`: root domain (e.g. `https://coder.example.com`)
+   - `CODER_WILDCARD_ACCESS_URL`: wildcard domain (e.g. `*.example.com`).
+
+1. Start the Caddy server:
+
+   If you're [keeping Caddy running](https://caddyserver.com/docs/running) via a system service:
+
+   ```sh
+   sudo systemctl restart caddy
+   ```
+
+   Or run a standalone server:
+
+   ```sh
+   caddy run
+   ```
+
+1. Optionally, use [ufw](https://wiki.ubuntu.com/UncomplicatedFirewall) or another firewall to disable external traffic outside of Caddy.
+
+   ```sh
+   # 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
+   ```
+
+1. Navigate to your Coder URL! A TLS certificate should be auto-generated on your first visit.
+
+## Generating wildcard certificates
+
+By default, this configuration uses Caddy's [on-demand TLS](https://caddyserver.com/docs/caddyfile/options#on-demand-tls) to generate a certificate for each subdomain (e.g. `app1.coder.example.com`, `app2.coder.example.com`). When users visit new subdomains, such as accessing [ports on a workspace](../../networking/port-forwarding.md), 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](https://github.com/caddy-dns) module for your DNS provider (e.g. CloudFlare, Route53).
+
+   - Docker: [Build an custom Caddy image](https://github.com/docker-library/docs/tree/master/caddy#adding-custom-caddy-modules) with the module for your DNS provider. Be sure to reference the new image in the `docker-compose.yaml`.
+
+   - Standalone: [Download a custom Caddy build](https://caddyserver.com/download) with the module for your DNS provider. If you're using Debian/Ubuntu, you [can configure the Caddy package](https://caddyserver.com/docs/build#package-support-files-for-custom-builds-for-debianubunturaspbian) to use the new build.
+
+1. Edit your `Caddyfile` and add the necessary credentials/API tokens to solve the DNS challenge for wildcard certificates.
+
+   ```diff
+   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](https://github.com/caddy-dns/route53).
diff --git a/examples/web-server/caddy/docker-compose.yaml b/examples/web-server/caddy/docker-compose.yaml
@@ -0,0 +1,57 @@
+version: "3.9"
+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_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:14.2"
+    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:
