Learning Caddy - Production Deployment & Best Practices

#Introduction

Congratulations — you made it to the final episode! Over 30 episodes you've learned the concepts, installation, the Caddyfile, automatic HTTPS, reverse proxying, load balancing, security, Docker, Kubernetes, and even plugins. Episode 30 brings it all together into one: how to deploy Caddy to production properly.

#Pre-Production Checklist

#Before Go-Live

• HTTPS active and tested for all domains.
• Automatic renewal running — check the certificate storage.
• Logs configured and sent to an aggregation system.
• Monitoring installed — health endpoint and metrics.
• Health checks active for all backends.
• Security headers applied.
• Certificate and configuration backups available.
• Disaster recovery plan tested.

caddy version
caddy validate --config Caddyfile

caddy validate --config Caddyfile checks the configuration before use. Run it on every change — it prevents errors that would take production down.

#Caddyfile Best Practices

#Snippets, Env Vars, and Version Control

• Use snippets for repetitive configuration (episode 2).
• Store secrets in environment variables, not in files (episode 4).
• Set global options correctly at the top.
• Give clear names to matchers and snippets.
• Comment complex logic.
• Keep the Caddyfile in Git.
• Always validate before deploying.

{
    email admin@example.com
    admin 127.0.0.1:2019
}
 
(common) {
    encode zstd gzip
    header {
        X-Content-Type-Options nosniff
        X-Frame-Options DENY
        -Server
    }
}
 
example.com {
    import common
    root * /var/www
    try_files {path} /index.html
    file_server
}
 
api.example.com {
    import common
    reverse_proxy {
        to api-1:3000 api-2:3000
        lb_policy round_robin
        health_uri /healthz
        health_interval 10s
    }
}

#Security Hardening

#Strengthening the System

• Run Caddy as a non-root user — the package installer already does this.
• Restrict file permissions on the Caddyfile and private keys.
• Keep the admin API on localhost.
• Set the firewall to open only the ports needed.
• Update Caddy regularly.
• Apply security headers on all sites.
• TLS 1.3 as the default.
• Turn off features that aren't used.
• Use secret management for credentials.

curl -I https://example.com

#Performance Tuning

#Optimizing for Load

• Enable encode zstd gzip.
• Set Cache-Control for static assets.
• Keep HTTP/2 and HTTP/3 active.
• Adjust connection timeouts.
• Tune the load balancer with health checks.
• Limit resources via systemd or Docker.

[Service]
MemoryMax=512M
CPUWeight=100
Restart=on-failure

#Day-to-Day Operations

#Graceful Reload and Deployment

caddy reload --config Caddyfile

#Log Rotation and Alerting

• Rotate logs on the local server (episode 22).
• Alert when a health check fails or a certificate is about to expire.

#High Availability

#Avoiding a Single Point of Failure

• Run multiple Caddy instances.
• Put an external load balancer in front.
• Use DNS-based failover or VRRP.
• Share certificate storage between instances.
• Synchronize the configuration of all instances.

#Common Pitfalls

#Mistakes That Happen Often

• Port 80/443 not open — HTTPS fails.
• DNS not pointing to the server — ACME issuance fails.
• Wrong storage permissions — certificates can't be written.
• Localhost in production — no automatic HTTPS.
• Wrong matchers — routing doesn't behave as expected.

#Troubleshooting and Migration

#Diagnostic Flow

1. Read the error and access logs.
2. Run caddy validate on the Caddyfile.
3. Try caddy run in the foreground with --debug.
4. Check certificate status via the admin API.
5. Verify DNS with dig or nslookup.
6. Test with curl and openssl s_client.
7. Check open ports with ss -tlnp.
8. Inspect file permissions.

#Migrating from NGINX and Apache

• Manual HTTPS → remove the certificate blocks, let Caddy be automatic.
• server blocks / virtual hosts → change them into site blocks.
• location blocks → replace them with handle + matchers.
• try_files → Caddy syntax is similar, without $.
• upstream → write the backends directly in reverse_proxy.

#Conclusion

Episode 30 closes the series with production readiness: a pre-production checklist, Caddyfile best practices with snippets and env vars, security hardening, performance tuning, operations with caddy reload, high availability, common pitfalls, a troubleshooting flow, and a migration guide from NGINX or Apache.

The essentials to take home:

• Validate with caddy validate before every deploy.
• Snippets, env vars, and Git keep the Caddyfile maintainable.
• Hardening: non-root user, firewall, security headers, TLS 1.3.
• caddy reload delivers changes without downtime.
• Health checks and shared storage are the key to high availability.
• Follow a structured troubleshooting flow, don't guess.

The Learning Caddy series is complete! You now have a full foundation: from web server concepts, the Caddyfile, automatic HTTPS, reverse proxying, load balancing, security, to Docker and Kubernetes deployment. Practice it in a homelab or a real project, and for deeper study, explore the Learning Nginx, Learning Traefik, or Learning PKI series — each technology opens a new perspective that enriches how you build web infrastructure. See you in the next series!