devops/kamal: Enhancing Kamal 2 with Caddy as Frontend Proxy

[dmitry]

The Challenge with kamal-proxy

While Kamal 2's built-in kamal-proxy is great for zero-downtime deployments, it has some limitations compared to full-featured web servers like Traefik, Nginx, or Caddy. The main issues include:

1. Limited SSL/TLS configuration options
2. Basic routing capabilities
3. Restricted customization for headers, timeouts, and other advanced features
4. Limited integration with external certificate authorities

The Solution: Caddy + kamal-proxy Architecture

We can get the best of both worlds by:

1. Using Caddy as the frontend proxy handling HTTPS and advanced routing
2. Keeping kamal-proxy internally for zero-downtime deployments
3. Connecting them through Docker's internal networking

Here's how to set it up:

1. Configure kamal-proxy

First, modify kamal-proxy's boot configuration to not publish ports to the host:

#!/bin/sh
# .kamal/hooks/pre-deploy
kamal proxy boot_config set \
  --publish false

2. Add Caddy as an Accessory

Add this to your config/deploy.yml:

accessories:
  caddy:
    service: caddy
    image: caddy:2.8-alpine
    cmd: "caddy run --config /etc/caddy/Caddyfile"
    files:
      - config/caddy/Caddyfile:/etc/caddy/Caddyfile
    options:
      restart: always
      publish:
        - "80:80"
        - "443:443"
        - "443:443/udp"
    directories:
      - ./config/caddy/data:/data
      - ./config/caddy/config:/config
    network: kamal
    roles:
      - web

3. Create Caddyfile

Create config/Caddyfile:

myapp.example.com {
    reverse_proxy kamal-proxy:80
}

Benefits of This Setup

1. Full HTTPS Control: Caddy handles SSL/TLS with automatic Let's Encrypt integration
2. Advanced Features: Access to Caddy's rich feature set (headers, redirects, middleware)
3. Zero-Downtime: Keep kamal-proxy's seamless deployment capabilities
4. Better Security: Proper layered architecture with frontend proxy
5. Flexibility: Easy to add more complex routing, caching, or security rules

Usage

Deploy as normal with kamal deploy. Caddy will handle external traffic on ports 80/443, and forward requests to kamal-proxy, which manages your application containers.

Notes

• Remember to configure DNS to point to your server's IP address
• Caddy automatically handles HTTPS certificates
• The internal kamal-proxy is still required for zero-downtime deployments
• You can customize the Caddyfile for advanced use cases (rate limiting, caching, etc.)

This setup gives you the power of a proper web server while maintaining Kamal's deployment benefits.

TODO

• Add examples in the Caddyfile
• Add explanations about the cloudflare
• How to redirect to www? basecamp/kamal#1214