Caddy Reverse Proxy

Caddy is a web server with automatic HTTPS. It obtains and renews certificates automatically, redirects HTTP to HTTPS, and provides a simple configuration syntax.

Quick Reference

Task Syntax

Basic proxy reverse_proxy backend:8080

Multiple upstreams reverse_proxy node1:80 node2:80

Path routing handle /api/* { reverse_proxy api:8080 }

Strip path prefix handle_path /api/* { reverse_proxy api:8080 }

Set request header header_up Host localhost

Remove response header header_down -Server

Wildcard cert tls { dns cloudflare {env.CF_API_TOKEN} }

Reload config caddy reload --config /etc/caddy/Caddyfile

Basic Patterns

Simple Reverse Proxy

example.com { reverse_proxy backend:8080 }

Multiple Sites

app.example.com { reverse_proxy app:3000 }

api.example.com { reverse_proxy api:8080 }

Path-Based Routing

example.com { handle /api/* { reverse_proxy api:8080 } handle { reverse_proxy frontend:3000 } }

Strip Path Prefix

example.com { handle_path /api/* { reverse_proxy api:8080 # /api/users → /users } }

Header Manipulation

example.com { reverse_proxy backend:8080 { # Set Host header (required by some backends) header_up Host localhost

    # Add client IP
    header_up X-Real-IP {remote_host}

    # Remove sensitive header
    header_up -Authorization

    # Remove server identity from response
    header_down -Server
}

}

Docker Integration

Proxy to Container (Same Network)

docker-compose.yml

services: caddy: image: caddy:2-alpine ports: - "80:80" - "443:443" volumes: - ./Caddyfile:/etc/caddy/Caddyfile:ro - caddy_data:/data networks: - web

app: image: myapp networks: - web expose: - "8080"

Caddyfile - use container name as hostname

example.com { reverse_proxy app:8080 }

Proxy to Host Service

services: caddy: extra_hosts: - "host.docker.internal:host-gateway"

example.com { reverse_proxy host.docker.internal:8080 }

TLS Configuration

Automatic (Default)

Caddy automatically obtains certificates when:

• Domain DNS points to server

• Ports 80/443 accessible

Wildcard Certificates

Requires DNS provider plugin:

*.example.com { tls { dns cloudflare {env.CF_API_TOKEN} }

@app1 host app1.example.com
handle @app1 {
    reverse_proxy app1:8080
}

@app2 host app2.example.com
handle @app2 {
    reverse_proxy app2:8080
}

}

Internal/Development

localhost { tls internal reverse_proxy app:8080 }

Request Matchers

Path matching

@api path /api/*

Header matching

@websocket header Connection Upgrade

Method matching

@post method POST

Combined (AND logic)

@api_post { path /api/* method POST }

Use matcher

handle @api { reverse_proxy api:8080 }

Load Balancing

example.com { reverse_proxy node1:80 node2:80 node3:80 { lb_policy round_robin health_uri /health health_interval 30s } }

Common Configurations

Security Headers

(security) { header { Strict-Transport-Security "max-age=31536000; includeSubDomains" X-Content-Type-Options nosniff X-Frame-Options SAMEORIGIN Referrer-Policy strict-origin-when-cross-origin } }

example.com { import security reverse_proxy backend:8080 }

www Redirect

www.example.com { redir https://example.com{uri} permanent }

SPA (Single Page App)

example.com { root * /srv try_files {path} /index.html file_server }

gRPC / HTTP/2 Cleartext

example.com { reverse_proxy h2c://grpc-server:9000 }

Global Options

{ email admin@example.com

# Use staging for testing
# acme_ca https://acme-staging-v02.api.letsencrypt.org/directory

}

example.com { # site config }

Reference Files

File When to Read

reverse-proxy.md Load balancing, health checks, transport options

caddyfile-syntax.md Matchers, handle blocks, directives

tls-certificates.md DNS challenge, wildcards, mTLS

docker-patterns.md Docker Compose, networks, host access

troubleshooting.md Common errors and diagnostics

Common Issues

Problem Solution

"no upstreams available" Check backend running, same Docker network

"connection refused" Backend binding to 0.0.0.0, not 127.0.0.1

Certificate not obtained Check DNS points to server, ports 80/443 open

403 Forbidden Backend needs header_up Host localhost

WebSocket fails Usually works; check flush_interval -1 for SSE

Verification Commands

Validate config

caddy validate --config /etc/caddy/Caddyfile

Format config

caddy fmt --overwrite /etc/caddy/Caddyfile

Reload (zero-downtime)

caddy reload --config /etc/caddy/Caddyfile

Debug mode

Add to global options: { debug }

Check certificate

openssl s_client -connect example.com:443 -servername example.com

Official Documentation

Topic URL

Caddyfile https://caddyserver.com/docs/caddyfile

reverse_proxy https://caddyserver.com/docs/caddyfile/directives/reverse_proxy

Automatic HTTPS https://caddyserver.com/docs/automatic-https

Common Patterns https://caddyserver.com/docs/caddyfile/patterns