Caddy as Reverse Proxy

Caddy, when configured as a reverse proxy, automatically provisions, renews, and manages TLS certificates for your domains using ACME providers like Let's Encrypt or ZeroSSL, enabling HTTPS by default without manual intervention. This feature simplifies secure web server deployment by eliminating the need for manual certificate management tasks.

Understanding Caddy's Automatic HTTPS

Caddy's primary differentiator is its zero-configuration approach to HTTPS. When Caddy receives a request for a domain, it attempts to obtain a TLS certificate for that domain if one does not already exist and is not explicitly configured. This process leverages the Automatic Certificate Management Environment (ACME) protocol.

How ACME and Caddy Interact

1. Domain Resolution: Caddy identifies the domain name associated with the incoming request.
2. Certificate Check: It checks its local storage for an existing, valid certificate for that domain.
3. ACME Challenge: If no valid certificate is found, Caddy initiates an ACME challenge with a configured ACME provider (defaulting to Let's Encrypt, with ZeroSSL as a fallback). The most common challenge types are HTTP-01 and DNS-01.
   • HTTP-01 Challenge: Caddy creates a temporary file at a specific path (/.well-known/acme-challenge/) on the server. The ACME provider then attempts to access this file via HTTP on port 80 to verify domain ownership. This requires Caddy to be publicly accessible on port 80.
   • DNS-01 Challenge: Caddy instructs the ACME provider to verify domain ownership by checking for a specific TXT record in the domain's DNS zone. This method is required for wildcard certificates and can be used when port 80 is not available. It requires Caddy to have credentials for a supported DNS provider.
4. Certificate Issuance: Upon successful challenge completion, the ACME provider issues a TLS certificate for the domain.
5. Certificate Storage: Caddy stores the certificate and its private key securely on the disk.
6. Automatic Renewal: Caddy monitors certificate expiration dates and automatically renews them well in advance (typically 30 days before expiration) using the same ACME challenge process.
7. OCSP Stapling: Caddy also automatically fetches and staples OCSP responses to certificates, improving client performance and privacy by allowing clients to verify certificate revocation status without contacting the Certificate Authority directly.

Basic Reverse Proxy Configuration with Automatic HTTPS

A minimal Caddyfile configuration for a reverse proxy implicitly enables automatic HTTPS.

Simple Reverse Proxy Example

yourdomain.com {
    reverse_proxy localhost:8080
}

In this example:
* yourdomain.com: This is the site label. Caddy will listen for requests to this domain on both ports 80 (for HTTP redirects and ACME challenges) and 443 (for HTTPS).
* reverse_proxy localhost:8080: This directive forwards all incoming requests for yourdomain.com to an upstream application running on localhost at port 8080.

When Caddy starts with this configuration, it performs the following steps automatically:
1. Attempts to obtain a TLS certificate for yourdomain.com from an ACME provider.
2. Sets up HTTP-to-HTTPS redirects for all traffic on port 80.
3. Serves yourdomain.com over HTTPS using the obtained certificate.

Running Caddy

To run Caddy with this configuration:

1. Save the content above as Caddyfile in your desired directory.
2. Navigate to that directory in your terminal.
3. Execute: caddy run

For production environments, running Caddy as a systemd service or within a Docker container is recommended.

Advanced HTTPS Configurations

Custom Certificates

If you have pre-existing TLS certificates (e.g., from an enterprise CA, or wildcard certificates obtained manually), Caddy can be configured to use them instead of automatically provisioning.

yourdomain.com {
    tls /path/to/your/cert.pem /path/to/your/key.pem
    reverse_proxy localhost:8080
}

• tls /path/to/your/cert.pem /path/to/your/key.pem: Specifies the full chain certificate file and the private key file. Caddy will use these files and will not attempt to provision a certificate for yourdomain.com.

Wildcard Certificates with DNS-01 Challenge

Wildcard certificates (*.yourdomain.com) require the DNS-01 ACME challenge because the HTTP-01 challenge cannot prove ownership for arbitrary subdomains. This necessitates configuring Caddy with credentials for your DNS provider.

*.yourdomain.com {
    tls {
        dns cloudflare {
            api_token "YOUR_CLOUDFLARE_API_TOKEN"
        }
    }
    reverse_proxy localhost:8080
}

• tls { dns cloudflare { ... } }: This block tells Caddy to use the DNS-01 challenge with the Cloudflare DNS provider.
• api_token "YOUR_CLOUDFLARE_API_TOKEN": Replace this with your actual Cloudflare API token. Caddy supports numerous DNS providers via plugins. Refer to the Caddy documentation for specific provider configurations.

Multiple Domains and Site Blocks

Caddy can serve multiple domains, each with its own automatic HTTPS.

yourdomain.com {
    reverse_proxy localhost:8080
}

anotherdomain.org {
    reverse_proxy localhost:8081
}

Caddy will independently provision and manage certificates for both yourdomain.com and anotherdomain.org.

HTTP-01 vs. DNS-01 Challenge Comparison

Feature	HTTP-01 Challenge	DNS-01 Challenge
Verification Method	Serving a file on port 80	Adding a TXT record to DNS
Required Port	80 (for ACME challenge)	No specific port, only DNS access
Wildcard Support	No	Yes (*.yourdomain.com)
Internal Servers	Not suitable if Caddy is not publicly accessible	Suitable for internal servers if DNS is manageable
Configuration	Usually automatic, no extra config	Requires DNS provider credentials and plugin
Firewall Needs	Port 80 must be open to the internet	No inbound ports needed on Caddy host for challenge

ACME Providers

Caddy defaults to using Let's Encrypt for certificate provisioning. ZeroSSL is used as a fallback. You can explicitly configure which ACME provider to use.

yourdomain.com {
    tls your_email@example.com {
        ca https://acme-v02.api.letsencrypt.org/directory
    }
    reverse_proxy localhost:8080
}

• ca https://acme-v02.api.letsencrypt.org/directory: Specifies the ACME CA URL.
• your_email@example.com: Providing an email address is recommended for ACME account registration and important notifications from the CA.

Managing Certificates

Caddy manages certificates automatically, but understanding its storage and manual options can be useful.

Certificate Storage

By default, Caddy stores certificates, private keys, and ACME account information in a data directory. The exact location depends on the operating system and how Caddy is run:
* Linux: /var/lib/caddy/.local/share/caddy (when run as root via systemd) or $HOME/.local/share/caddy (when run as a user).
* Docker: Within the container's /data volume.

This directory should be persistent (e.g., a mounted volume in Docker) to avoid re-provisioning certificates on restarts.

Manual Renewal and Revocation

While Caddy automates renewal, direct interaction with the certificate store is rarely needed.
* Renewal: If an immediate renewal is required (e.g., after a certificate compromise), you can delete the specific certificate files from Caddy's data directory. Caddy will then attempt to provision a new one on the next startup or request.
* Revocation: Certificate revocation is an advanced operation, typically performed if a private key is compromised. Caddy does not provide a direct command-line utility for revocation. This would usually be done through the ACME provider's API or a dedicated client if necessary.

Troubleshooting Common HTTPS Issues

Firewall Configuration

Ensure ports 80 and 443 are open to inbound traffic on your Caddy server. Port 80 is crucial for the HTTP-01 ACME challenge and for HTTP-to-HTTPS redirects.

DNS Propagation

If using the DNS-01 challenge, verify that your DNS records (specifically the TXT record for the challenge) have propagated correctly. Use tools like dig or online DNS lookup services. Incorrect or slow DNS propagation can prevent certificate issuance.

ACME Rate Limits

ACME providers like Let's Encrypt have rate limits on certificate issuance. Repeated failed attempts can lead to temporary blocks.
* Staging Environment: Use the ACME staging environment for testing to avoid hitting production rate limits.
caddyfile yourdomain.com { tls your_email@example.com { ca https://acme-staging-v02.api.letsencrypt.org/directory } reverse_proxy localhost:8080 }
* Consolidate Domains: If serving many subdomains, consider a wildcard certificate to reduce the number of individual certificate requests.

Caddy Logs

Caddy's logs provide detailed information about certificate provisioning attempts, renewals, and any errors. Check the logs for specific error messages if HTTPS is not working as expected.
* Default Log Location: Logs are typically written to standard output (stdout) or a configured log file.
* Verbose Logging: You can increase log verbosity for more diagnostic information.

{
    log {
        output file /var/log/caddy/caddy.log
        level DEBUG
    }
}

yourdomain.com {
    reverse_proxy localhost:8080
}

Deployment Considerations

Docker

When deploying Caddy in Docker, ensure that the data directory is mapped to a persistent volume.

version: '3.8'
services:
  caddy:
    image: caddy:latest
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - caddy_data:/data # Persistent storage for certificates
      - caddy_config:/config
  myapp:
    image: myapp:latest
    restart: unless-stopped
    expose:
      - "8080" # Internal port, not exposed externally

volumes:
  caddy_data:
  caddy_config:

Systemd Service

For bare-metal or VM deployments, running Caddy as a systemd service is standard practice. The official Caddy documentation provides example caddy.service files that configure Caddy to run as a dedicated user and manage its data directory correctly.

Resource Usage

Caddy is lightweight. Certificate management operations consume minimal resources and typically occur in the background. The primary resource consumption will be related to proxying traffic.

Security Best Practices

Caddy's automatic HTTPS handles many security aspects by default:
* Strong TLS Ciphers: Caddy uses modern and secure TLS cipher suites.
* HTTP Strict Transport Security (HSTS): Caddy can automatically add the Strict-Transport-Security header, instructing browsers to always connect via HTTPS.
* OCSP Stapling: Reduces latency and enhances privacy.

While Caddy handles much of the TLS complexity, general security practices remain relevant:
* Keep Caddy Updated: Regularly update Caddy to the latest version to benefit from security patches and new features.
* Least Privilege: Run Caddy with the minimum necessary permissions. The official systemd service files configure Caddy to run as a non-root user.
* Firewall: Restrict access to your upstream applications (e.g., localhost:8080) so they are only accessible from the Caddy instance.
* Access Control: Implement additional access control or authentication if required for specific routes or applications behind the proxy.