# 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 in your project root:

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

## 常见问题

**Q: Caddy 和 Nginx 性能差距大吗？**
A: 对于大多数使用场景，差距可以忽略。Nginx 在超高并发（10万+ 连接）场景下有轻微优势。Caddy 的 Go 实现在中等负载下性能优秀，而自动 HTTPS 和简洁配置带来的运维效率提升远超性能差异。

**Q: 可以在生产环境用吗？**
A: 完全可以。Caddy 被大量公司和项目用于生产环境。其默认安全配置（HTTPS、安全头、现代 TLS）使得生产部署比手动配置 Nginx + Certbot 更安全。

**Q: 如何处理多个域名的 HTTPS？**
A: 在 Caddyfile 中列出每个域名即可，Caddy 会为每个域名自动获取独立证书。也支持通配符证书（需要 DNS 挑战）。

## 来源与致谢

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

---
Source: https://tokrepo.com/en/workflows/e8cf7b74-34a9-11f1-9bc6-00163e2b0d79
Author: AI Open Source