One Open Source Project a Day (Part 46): Caddy - Modern Web Server with Automatic HTTPS and HTTP/3 Support

Deep dive into Caddy, a fast and extensible multi-platform web server written in Go, with automatic HTTPS by default, supporting HTTP/1.1, HTTP/2, HTTP/3, zero-configuration ready, production-ready

·12 min read·Tools
open-sourceCaddyWeb ServerGoHTTPSHTTP/3Reverse ProxyAutomatic Certificates

Introduction

"Every site on HTTPS"

This is Part 46 of the "One Open Source Project a Day" series. Today's project is Caddy (GitHub).

Still struggling with HTTPS certificate configuration? Still using complex Nginx or Apache configurations? Caddy is a fast and extensible multi-platform web server written in Go, with automatic HTTPS by default, supporting HTTP/1.1, HTTP/2, HTTP/3, zero-configuration ready, production-ready. Since its release in 2014, it has served trillions of HTTPS requests and managed millions of TLS certificates, making it the first web server to use HTTPS by default.

Why it matters:

  • 🚀 Automatic HTTPS: Enabled by default, automatic TLS certificate management (Let's Encrypt, ZeroSSL)
  • 🌐 HTTP/3 Support: Default support for HTTP/1.1, HTTP/2, HTTP/3
  • ⚡ High Performance: Written in Go, single binary file, no external dependencies
  • 🔧 Easy Configuration: Simple Caddyfile configuration, JSON API dynamic configuration
  • 🛡️ Production-Ready: Served trillions of requests, managed millions of certificates
  • 🔌 Highly Extensible: Modular architecture, rich plugin ecosystem
  • 📦 Zero Dependencies: Single static binary file, doesn't even need libc

What You'll Learn

  • Caddy's core features: automatic HTTPS, HTTP/3, reverse proxy
  • Caddyfile configuration syntax and JSON API configuration
  • Comparison and advantages over Nginx and Apache
  • Real-world use cases: static websites, reverse proxy, API gateway
  • Plugin system and extension mechanisms
  • Production deployment best practices

Prerequisites

  • Understanding of basic web server concepts (HTTP, HTTPS, reverse proxy)
  • Basic understanding of TLS/SSL certificates
  • Understanding of Go language (optional, for understanding implementation)
  • Experience with Nginx or Apache (optional, for comparison)

Project Background

Project Overview

Caddy is a fast and extensible multi-platform web server written in Go, with its most prominent feature being automatic HTTPS by default. It is the first web server to use HTTPS by default, making HTTPS the standard rather than an option.

Core Features:

  • Automatic HTTPS: Enabled by default, automatically obtains certificates from Let's Encrypt or ZeroSSL
  • HTTP/3 Support: Default support for HTTP/1.1, HTTP/2, HTTP/3
  • Zero Configuration: Simplest configuration to run
  • High Performance: Written in Go, single binary file, no external dependencies
  • Production-Ready: Served trillions of requests, managed millions of certificates
  • Highly Extensible: Modular architecture, rich plugin ecosystem
  • Dynamic Configuration: Supports JSON API for online configuration changes
  • Multi-Platform: Supports Linux, macOS, Windows

Core Problems Solved:

  • Complex HTTPS configuration, cumbersome certificate management
  • Complex traditional web server configuration, steep learning curve
  • HTTP/3 support requires additional configuration
  • Certificate expiration causing service interruption
  • Complex multi-site management

Target Users:

  • Developers who need to quickly deploy HTTPS websites
  • Operations engineers who need to simplify web server configuration
  • Applications requiring HTTP/3 support
  • Teams needing reverse proxy and load balancing
  • Individual developers who want zero-configuration HTTPS

Author/Team Introduction

  • Author: Matthew Holt (@mholt6)
  • Background: Started developing Caddy in 2014 while studying computer science at Brigham Young University
  • Philosophy: Make HTTPS the standard, simplify web server configuration
  • Project Ownership: Project of ZeroSSL (HID Global company)
  • Community: Hundreds of contributors, active community support

Project Name Origin: The name "Caddy" comes from the fact that this software helps with the tedious, mundane tasks of serving the Web, and is also a single place for multiple things to be organized together (like a golf caddy).

Project Statistics

Tech Stack:

  • Language: Go (97.9%)
  • Core Features: HTTP/1.1, HTTP/2, HTTP/3, TLS, automatic certificate management
  • Dependencies: CertMagic (automatic certificate management library)
  • Platforms: Linux, macOS, Windows

Key Milestones:

  • 2014: Project launch, first web server with HTTPS by default
  • 2020: Caddy 2.0 release, complete rewrite
  • 2021: Caddy 2.6 enables HTTP/3 by default
  • Present: Served trillions of HTTPS requests, managed millions of certificates

Main Features

Core Purpose

Caddy's core purpose is to provide a modern, easy-to-use web server that enables developers to:

  1. Zero-Configuration HTTPS: Automatically obtain and manage TLS certificates
  2. High-Performance Service: Support HTTP/1.1, HTTP/2, HTTP/3
  3. Reverse Proxy: Flexible reverse proxy and load balancing
  4. Static File Serving: Efficient static file server
  5. Dynamic Configuration: Online configuration changes via JSON API
  6. Multi-Site Management: Easily manage hundreds of sites
  7. Plugin Extensions: Rich plugin ecosystem

Use Cases

  1. Static Website Hosting

    • Personal blogs, documentation sites
    • Single Page Application (SPA) deployment
    • Static resource CDN

  2. Reverse Proxy

    • Microservices API gateway
    • Load balancing
    • Service discovery integration

  3. Development Environment

    • Local HTTPS development
    • Automatic certificate management
    • Quick prototype deployment

  4. Production Environment

    • High-availability web services
    • Multi-site management
    • Automatic certificate renewal

  5. Containerized Deployment

    • Docker containers
    • Kubernetes Ingress
    • Cloud-native applications

Quick Start

Installation:

# macOS
brew install caddy
 
# Linux (using package manager)
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install caddy
 
# Or download binary directly
wget https://github.com/caddyserver/caddy/releases/latest/download/caddy_2.11.2_linux_amd64.tar.gz
tar -xzf caddy_2.11.2_linux_amd64.tar.gz
sudo mv caddy /usr/local/bin/

Simplest Configuration (Caddyfile):

# Automatic HTTPS, zero configuration
localhost
 
respond "Hello, Caddy!"

Run:

# Using Caddyfile
caddy run
 
# Or specify config file
caddy run --config Caddyfile
 
# Run in background
caddy start --config Caddyfile

Access:

Reverse Proxy Example:

example.com {
    reverse_proxy localhost:8080
}

Static File Serving:

example.com {
    root * /var/www/html
    file_server
}

Core Features

  1. Automatic HTTPS

    • HTTPS enabled by default
    • Automatically obtains certificates from Let's Encrypt or ZeroSSL
    • Automatic renewal, no manual management
    • Supports local CA for internal names and IPs
    • Multi-certificate authority fallback

  2. HTTP/3 Support

    • Default support for HTTP/1.1, HTTP/2, HTTP/3
    • Based on QUIC protocol
    • Automatic fallback (falls back to HTTP/2 when UDP unavailable)
    • Backward compatible

  3. Flexible Configuration

    • Caddyfile: Simple and readable configuration syntax
    • JSON API: Native JSON configuration, dynamic updates
    • Config Adapters: Supports YAML, TOML, NGINX config formats
    • Online Configuration Changes: No restart required, graceful reload

  4. Reverse Proxy

    • Flexible routing rules
    • Load balancing (round-robin, least connections, IP hash, etc.)
    • Health checks
    • Service discovery integration (Consul, Kubernetes, etc.)
    • WebSocket support

  5. Static File Serving

    • Efficient file server
    • Directory browsing
    • File compression (gzip, brotli)
    • Cache control
    • Range request support

  6. Security Features

    • TLS 1.3 support
    • OCSP Stapling
    • HSTS support
    • Automatic security headers
    • Prevents service interruption due to TLS/OCSP/certificate issues

  7. Extensibility

    • Modular architecture
    • Rich plugin ecosystem
    • Custom middleware
    • Plugin hot-loading

  8. Production-Ready

    • Served trillions of requests
    • Managed millions of certificates
    • Supports hundreds of thousands of sites
    • High availability design
    • Comprehensive monitoring and logging

Project Advantages

Comparison ItemCaddyNginxApache
HTTPS Configuration✅ Automatic, zero-config⚠️ Manual certificate configuration⚠️ Manual certificate configuration
HTTP/3 Support✅ Enabled by default⚠️ Requires additional modules⚠️ Requires additional modules
Configuration Complexity✅ Caddyfile simple⚠️ Complex config files⚠️ Complex config files
Dynamic Configuration✅ JSON API, no restart⚠️ Requires config reload⚠️ Requires config reload
Certificate Management✅ Automatic renewal❌ Manual management❌ Manual management
Performance✅ Go-written, high performance✅ C-written, high performance⚠️ Process model, average performance
Memory Safety✅ Go memory safety guarantees⚠️ C language, requires attention⚠️ C language, requires attention
Dependencies✅ Single binary, no dependencies⚠️ Requires system libraries⚠️ Requires system libraries
Learning Curve✅ Simple, quick to learn⚠️ Steep⚠️ Steep
Plugin Ecosystem✅ Rich plugins✅ Rich modules✅ Rich modules

Why Choose Caddy?

  • Zero-Configuration HTTPS: Automatically obtain and manage certificates, no manual operation
  • Modern Protocols: Default HTTP/3 support, future-oriented
  • Simple Configuration: Caddyfile syntax simple, JSON API flexible
  • Production-Ready: Served trillions of requests, managed millions of certificates
  • Highly Extensible: Modular architecture, rich plugin ecosystem
  • Single Binary: No external dependencies, easy to deploy
  • Memory Safety: Written in Go, memory safety guarantees

Detailed Project Analysis

Architecture Design

Caddy adopts a modular, extensible architecture design, based on Go language, implementing feature extensions through module system.

Core Components:

Caddy
├── HTTP App (HTTP Server)
│   ├── HTTP/1.1 Support
│   ├── HTTP/2 Support
│   └── HTTP/3 Support (QUIC)
├── TLS App (TLS Management)
│   ├── Automatic Certificate Acquisition (CertMagic)
│   ├── Certificate Renewal
│   └── OCSP Stapling
├── Reverse Proxy Module
│   ├── Routing Rules
│   ├── Load Balancing
│   └── Health Checks
├── Static File Server
├── Middleware System
│   ├── Authentication
│   ├── Compression
│   ├── Logging
│   └── Caching
└── Configuration System
    ├── Caddyfile Parser
    ├── JSON API
    └── Config Adapters

Design Philosophy:

  1. Secure by Default: HTTPS enabled by default, security first
  2. Zero Configuration: Simplest configuration to run
  3. Modular: Features implemented through modules, easy to extend
  4. Dynamic Configuration: Supports online configuration changes, no restart
  5. Single Binary: No external dependencies, easy to deploy

Automatic HTTPS Implementation

Caddy's automatic HTTPS feature is implemented based on the CertMagic library, supporting multiple certificate authorities.

Workflow:

1. First HTTPS request
   ↓
2. Check if valid certificate exists locally
   ↓
3. If not, apply to Let's Encrypt or ZeroSSL
   ↓
4. Complete ACME challenge (HTTP-01, DNS-01, TLS-ALPN-01)
   ↓
5. Obtain and store certificate
   ↓
6. Automatic renewal (30 days before expiration)

Supported Certificate Authorities:

  • Let's Encrypt: Public domains
  • ZeroSSL: Public domains
  • Local CA: Internal names and IPs
  • Custom CA: Supports custom certificate authorities

ACME Challenge Types:

  • HTTP-01: Verify domain ownership via HTTP
  • DNS-01: Verify via DNS records
  • TLS-ALPN-01: Verify via TLS handshake

Configuration Examples:

# Automatic HTTPS (default)
example.com {
    respond "Hello, HTTPS!"
}
 
# Using specific email (Let's Encrypt)
example.com {
    email admin@example.com
    respond "Hello, HTTPS!"
}
 
# Disable automatic HTTPS
example.com {
    http_only
    respond "Hello, HTTP!"
}

HTTP/3 Support

Caddy 2.6+ enables HTTP/3 support by default, based on QUIC protocol.

HTTP/3 Features:

  • Based on QUIC: Uses UDP transport, not TCP
  • Multiplexing: No head-of-line blocking
  • Connection Migration: Maintains connection when IP address changes
  • 0-RTT: Fast connection establishment

Automatic Fallback:

HTTP/3 (QUIC/UDP)
    ↓ (UDP unavailable)
HTTP/2 (TCP)
    ↓ (HTTP/2 unavailable)
HTTP/1.1 (TCP)

Configuration:

# HTTP/3 enabled by default, no configuration needed
example.com {
    respond "Hello, HTTP/3!"
}
 
# Explicitly enable HTTP/3
example.com {
    protocols h1 h2 h3
    respond "Hello, HTTP/3!"
}
 
# Disable HTTP/3
example.com {
    protocols h1 h2
    respond "Hello, HTTP/2!"
}

Configuration System

Caddy supports multiple configuration methods, from simple Caddyfile to flexible JSON API.

Caddyfile Syntax:

# Global options
{
    email admin@example.com
    admin localhost:2019
}
 
# Site configuration
example.com {
    # Reverse proxy
    reverse_proxy localhost:8080
    
    # Static files
    root * /var/www/html
    file_server
    
    # Logging
    log {
        output file /var/log/caddy/access.log
    }
    
    # Compression
    encode gzip zstd
    
    # Security headers
    header {
        Strict-Transport-Security "max-age=31536000;"
        X-Content-Type-Options "nosniff"
    }
}

JSON API Configuration:

{
  "apps": {
    "http": {
      "servers": {
        "srv0": {
          "listen": [":443"],
          "routes": [
            {
              "match": [
                {
                  "host": ["example.com"]
                }
              ],
              "handle": [
                {
                  "handler": "reverse_proxy",
                  "upstreams": [
                    {
                      "dial": "localhost:8080"
                    }
                  ]
                }
              ]
            }
          ]
        }
      }
    },
    "tls": {
      "automation": {
        "policies": [
          {
            "subjects": ["example.com"],
            "issuers": [
              {
                "module": "acme",
                "email": "admin@example.com"
              }
            ]
          }
        ]
      }
    }
  }
}

Dynamic Configuration:

# Load configuration via API
curl -X POST http://localhost:2019/load \
  -H "Content-Type: application/json" \
  -d @config.json
 
# Get current configuration
curl http://localhost:2019/config/
 
# Update configuration
curl -X PATCH http://localhost:2019/config/ \
  -H "Content-Type: application/json" \
  -d '{"apps":{"http":{"servers":{"srv0":{"listen":[":443"]}}}}}'

Reverse Proxy Features

Caddy's reverse proxy features are very powerful, supporting load balancing, health checks, service discovery, etc.

Basic Reverse Proxy:

example.com {
    reverse_proxy localhost:8080
}

Load Balancing:

example.com {
    reverse_proxy localhost:8080 localhost:8081 localhost:8082 {
        # Load balancing strategy
        lb_policy least_conn  # Least connections
        # lb_policy round_robin  # Round-robin (default)
        # lb_policy ip_hash     # IP hash
        # lb_policy first       # First available
        
        # Health checks
        health_uri /health
        health_interval 10s
        health_timeout 5s
        
        # Failover
        fail_duration 30s
        max_fails 3
        unhealthy_status 500 502 503
    }
}

WebSocket Support:

example.com {
    reverse_proxy /ws localhost:8080 {
        # WebSocket upgrade
        header_up Connection "Upgrade"
        header_up Upgrade "websocket"
    }
}

Service Discovery:

example.com {
    reverse_proxy consul://service-name
    # Or
    reverse_proxy kubernetes://service-name:8080
}

Plugin System

Caddy's plugin system is very flexible, allowing feature extensions through modules.

Built-in Modules:

  • http: HTTP server
  • tls: TLS management
  • reverse_proxy: Reverse proxy
  • file_server: Static file server
  • encode: Compression
  • log: Logging
  • header: HTTP header operations

Third-party Plugins:

  • caddy-dns/cloudflare: Cloudflare DNS challenge
  • caddy-dns/route53: AWS Route53 DNS challenge
  • caddy-auth-portal: Authentication portal
  • caddy-rate-limit: Rate limiting
  • caddy-cache: HTTP caching

Using Plugins:

# Build Caddy with plugins using xcaddy
xcaddy build \
  --with github.com/caddy-dns/cloudflare \
  --with github.com/mholt/caddy-ratelimit

Performance Optimization

Caddy's performance optimization is mainly reflected in:

  1. Go Language Advantages: Compiled language, performance close to C
  2. Single Binary: No external dependencies, fast startup
  3. Concurrency Model: Go's goroutines achieve high concurrency
  4. Memory Management: Go's GC automatically manages memory
  5. Zero-Copy: Reduces data copying, improves performance

Performance Comparison (reference data):

  • Throughput: Comparable to Nginx
  • Memory Usage: Slightly higher than Nginx, but acceptable
  • CPU Usage: Comparable to Nginx
  • Startup Time: Faster than Nginx

Project Links and Resources

Official Resources

Related Resources

Target Audience

  • Web Developers: Need to quickly deploy HTTPS websites
  • Operations Engineers: Need to simplify web server configuration
  • DevOps Engineers: Need modern reverse proxy and load balancing
  • Individual Developers: Need zero-configuration HTTPS development environment
  • Enterprise Teams: Need production-grade web server with multi-site management

Welcome to my homepage to find more useful knowledge and interesting products

← Back to Blog