# Caddy — Fast Web Server with Automatic HTTPS

> Caddy is a modern web server with automatic HTTPS by default. Zero-config TLS certificates, reverse proxy, file server, and load balancer — all in a single binary.

## Install

Save the content below to `.claude/skills/` or append to your `CLAUDE.md`:

## Quick Use

```bash
# Install
curl -sS https://getcaddy.com | bash

# Serve current directory with HTTPS
caddy file-server --domain yourdomain.com

# Reverse proxy
caddy reverse-proxy --from yourdomain.com --to localhost:3000
```

Or with Docker:

```bash
docker run -d --name caddy -p 80:80 -p 443:443 
  -v caddy-data:/data -v ./Caddyfile:/etc/caddy/Caddyfile 
  caddy:latest
```

## Intro

**Caddy** is a powerful, extensible web server written in Go that features automatic HTTPS by default. Unlike traditional web servers that require manual certificate management, Caddy automatically obtains and renews TLS certificates from Let's Encrypt — making HTTPS deployment completely hands-free.

With 71.4K+ GitHub stars and Apache-2.0 license, Caddy is the most popular modern web server, known for its simplicity, security-by-default philosophy, and the elegant Caddyfile configuration format.

## What Caddy Does

- **Automatic HTTPS**: Obtains, renews, and manages TLS certificates automatically — zero config
- **Reverse Proxy**: Forward requests to backend services with load balancing and health checks
- **File Server**: Serve static files with directory listing, compression, and caching
- **HTTP/3**: Native QUIC/HTTP/3 support for faster connections
- **Virtual Hosts**: Host multiple sites on one server with per-site configuration
- **API Configuration**: RESTful API for dynamic config changes without restart
- **Extensible**: Plugin system for custom modules (auth, caching, WAF, etc.)

## Caddyfile Examples

### Simple Static Site

```
yourdomain.com {
    root * /var/www/html
    file_server
}
```

That's it. Caddy automatically:
- Gets a TLS certificate from Let's Encrypt
- Redirects HTTP to HTTPS
- Serves files from /var/www/html
- Handles certificate renewal

### Reverse Proxy

```
app.yourdomain.com {
    reverse_proxy localhost:3000
}

api.yourdomain.com {
    reverse_proxy localhost:8080
}

grafana.yourdomain.com {
    reverse_proxy localhost:3001
}
```

### With Middleware

```
yourdomain.com {
    # Compression
    encode gzip zstd

    # Security headers
    header {
        X-Frame-Options DENY
        X-Content-Type-Options nosniff
        Referrer-Policy strict-origin-when-cross-origin
        Strict-Transport-Security "max-age=31536000; includeSubDomains"
    }

    # Basic auth for /admin
    basicauth /admin/* {
        admin $2a$14$...hashed-password...
    }

    # Reverse proxy with load balancing
    reverse_proxy /api/* {
        to localhost:8001
        to localhost:8002
        to localhost:8003
        lb_policy round_robin
        health_uri /health
        health_interval 10s
    }

    # Static files
    root * /var/www/html
    file_server
}
```

## Self-Hosting

### Docker Compose

```yaml
services:
  caddy:
    image: caddy:latest
    ports:
      - "80:80"
      - "443:443"
      - "443:443/udp"  # HTTP/3
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy-data:/data
      - caddy-config:/config
    restart: unless-stopped

volumes:
  caddy-data:
  caddy-config:
```

### Single Binary

```bash
# Download
curl -sS https://getcaddy.com | bash

# Run with Caddyfile
caddy run --config /etc/caddy/Caddyfile

# Or as systemd service
sudo caddy start --config /etc/caddy/Caddyfile
```

## Key Features

### Automatic Certificate Management

Caddy handles the entire TLS lifecycle:

```
1. You specify a domain name in Caddyfile
2. Caddy checks if it has a valid certificate
3. If not, it contacts Let's Encrypt (ACME protocol)
4. Obtains certificate via HTTP-01 or TLS-ALPN-01 challenge
5. Installs certificate and starts serving HTTPS
6. Renews certificate before expiration (every ~60 days)
7. Zero downtime during renewal
```

Also supports:
- ZeroSSL (alternative to Let's Encrypt)
- Custom CA certificates
- Self-signed certificates for development
- Wildcard certificates via DNS challenge

### JSON API

Caddy can be configured entirely via REST API:

```bash
# Get current config
curl localhost:2019/config/

# Add a new site
curl -X POST localhost:2019/config/apps/http/servers/myserver 
  -H "Content-Type: application/json" 
  -d '{"listen": [":443"], "routes": [{"handle": [{"handler": "reverse_proxy", "upstreams": [{"dial": "localhost:3000"}]}]}]}'
```

### On-Demand TLS

Automatically get certificates for any domain that connects:

```
{
    on_demand_tls {
        ask http://localhost:5555/check  # Verify domain is allowed
    }
}

https:// {
    tls {
        on_demand
    }
    reverse_proxy localhost:8080
}
```

## Caddy vs Alternatives

| Feature | Caddy | Nginx | Traefik | Apache |
|---------|-------|-------|---------|--------|
| Auto HTTPS | Default | Certbot | Let's Encrypt | Certbot |
| Config | Caddyfile | nginx.conf | Labels/YAML | .htaccess |
| HTTP/3 | Yes | Experimental | Yes | No |
| Hot reload | Yes | Signal | Yes | Graceful |
| Single binary | Yes | Package | Yes | Package |
| Memory | ~20MB | ~5MB | ~50MB | ~30MB |
| Plugins | Go modules | C modules | Go plugins | C modules |

## FAQ

**Q: Is there a big performance gap between Caddy and Nginx?**
A: For most use cases, the difference is negligible. Nginx has a slight edge under very high concurrency (100K+ connections). Caddy's Go implementation performs well at moderate load, and the operational savings from automatic HTTPS and simpler configuration usually outweigh any performance delta.

**Q: Is it production-ready?**
A: Absolutely. Caddy is used in production by many companies and projects. Its secure defaults (HTTPS, security headers, modern TLS) make production deployment safer than hand-configuring Nginx + Certbot.

**Q: How do I handle HTTPS for multiple domains?**
A: List each domain in your Caddyfile — Caddy automatically obtains a separate certificate per domain. Wildcard certificates are also supported (requires DNS challenge).

## Source & Thanks

- GitHub: [caddyserver/caddy](https://github.com/caddyserver/caddy) — 71.4K+ ⭐ | Apache-2.0
- Website: [caddyserver.com](https://caddyserver.com)

---
Source: https://tokrepo.com/en/workflows/caddy-fast-web-server-automatic-https-e8cf7b74
Author: AI Open Source