# Caddy Reverse Proxy Stack

> Caddy with automatic HTTPS and multiple backends.

- Category: Web Servers & Reverse Proxies
- Difficulty: intermediate
- Components: caddy, whoami
- Tags: caddy, reverse-proxy, https, load-balancer
- Source: https://docker.recipes/web-servers/caddy-reverse-proxy-stack

## Overview

Caddy is a modern, open-source web server developed in Go that revolutionizes web server management with its automatic HTTPS capabilities and zero-configuration approach. Unlike traditional web servers like Apache or Nginx that require complex SSL certificate management, Caddy automatically obtains, renews, and configures Let's Encrypt certificates, making HTTPS deployment effortless for developers and system administrators. This stack combines Caddy's powerful reverse proxy functionality with multiple whoami backend services, creating a robust load-balancing solution that demonstrates real-world reverse proxy patterns. The whoami containers serve as lightweight HTTP services that return request information, making them perfect for testing load distribution, health checks, and reverse proxy behavior. This configuration showcases Caddy's built-in load balancing capabilities across multiple backend services while maintaining automatic HTTPS termination at the proxy level. DevOps teams managing multiple microservices, developers building distributed applications, and organizations transitioning from complex reverse proxy setups will find this stack particularly valuable. The combination eliminates the need for separate load balancers or complex SSL certificate orchestration tools, providing a single-binary solution that handles both reverse proxying and automatic certificate management with minimal operational overhead.

## Features

- Automatic Let's Encrypt certificate provisioning and renewal with zero manual intervention
- Built-in load balancing across multiple backend services with configurable algorithms
- Zero-downtime configuration reloads through Caddy's live config API
- HTTP/3 and HTTP/2 support with automatic protocol negotiation
- On-demand TLS certificate generation for dynamic domain scenarios
- Intelligent health checking and automatic backend failover
- Real-time request information display through whoami service integration
- Single binary deployment with no external dependencies or plugins required

## Use cases

- Multi-tenant SaaS applications requiring automatic subdomain SSL certificate management
- Development and staging environments for testing load balancing strategies
- Microservices architecture with multiple backend services behind a single entry point
- Legacy application modernization where HTTPS needs to be added without backend changes
- Homelab setups requiring reverse proxy for multiple self-hosted services
- DevOps training environments for teaching reverse proxy and load balancing concepts
- API gateway replacement for simpler architectures not requiring complex routing logic

## Prerequisites

- Minimum 256MB RAM available for Caddy proxy operations and certificate management
- Domain name with DNS control for automatic Let's Encrypt certificate validation
- Ports 80 and 443 available and accessible from the internet for HTTPS challenges
- Basic understanding of reverse proxy concepts and HTTP request routing
- Docker host with internet connectivity for Let's Encrypt ACME challenges
- Understanding of Caddyfile syntax for configuring routing rules and backend targets

## docker-compose.yml

```yaml
services:
  caddy:
    image: caddy:alpine
    container_name: caddy-proxy
    restart: unless-stopped
    ports:
      - "${CADDY_HTTP_PORT:-80}:80"
      - "${CADDY_HTTPS_PORT:-443}:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy_data:/data
      - caddy_config:/config

  backend-1:
    image: traefik/whoami:latest
    container_name: backend-1
    restart: unless-stopped

  backend-2:
    image: traefik/whoami:latest
    container_name: backend-2
    restart: unless-stopped

  backend-3:
    image: traefik/whoami:latest
    container_name: backend-3
    restart: unless-stopped

volumes:
  caddy_data:
  caddy_config:
```

## .env

```bash
# Caddy Proxy
CADDY_HTTP_PORT=80
CADDY_HTTPS_PORT=443
```

## Usage notes

- Caddy at http://localhost
- Configure Caddyfile for routing
- Automatic HTTPS with Let's Encrypt
- Load balancing built-in

## Troubleshooting

- Certificate validation failed: Ensure DNS records point to your server and ports 80/443 are publicly accessible for Let's Encrypt validation
- Backend connection refused: Verify whoami containers are running and accessible within Docker network using docker exec to test connectivity
- Caddyfile parse error on startup: Check Caddyfile syntax and ensure proper indentation, as Caddy is sensitive to configuration format
- Load balancing not working: Confirm all backend services are defined in Caddyfile upstream block and containers are healthy
- Permission denied accessing Caddyfile: Verify file ownership and that Caddyfile has proper read permissions for the caddy user inside container
- Certificate storage issues: Check that caddy_data volume has sufficient space and proper write permissions for certificate storage

