coder/examples/web-server/caddy/README.md

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.

Getting started

With docker-compose

1. Install Docker and Docker Compose

2. Start with our example configuration

   # 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)
   

3. Modify the 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. This is optional and can be removed.

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:

   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.

4. Configure Coder 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).

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.

Generating wildcard certificates

By default, this configuration uses Caddy's 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, 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 (e.g. CloudFlare, Route53).

   • Docker: Build an custom Caddy image 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 with the module for your DNS provider. If you're using Debian/Ubuntu, you can configure the Caddy package to use the new build.

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.