Learning Caddy - Docker Integration

#Introduction

Containers changed how applications are deployed, and Caddy is one of the most comfortable web servers for Docker. Its official image is lightweight, configuration comes from an easily mountable file, and logs go straight to stdout for container management. Episode 27 covers Docker integration comprehensively.

#Official Image and Basic Deployment

#Running the Container

The official caddy image is available on Docker Hub:

docker run -d -p 80:80 -p 443:443 \
  --name caddy \
  -v $PWD/Caddyfile:/etc/caddy/Caddyfile:ro \
  -v caddy_data:/data \
  -v caddy_config:/config \
  caddy:2

Important volumes:

• Caddyfile:/etc/caddy/Caddyfile — the configuration.
• caddy_data:/data — certificates and storage (must be persistent).
• caddy_config:/config — runtime configuration.

docker run -d -p 80:80 -p 443:443 caddy:2 maps the standard web ports to the container.

#Image Variants

• caddy:2 — the standard image.
• caddy:2-alpine — a smaller Alpine-based version.
• Custom builds with plugins use xcaddy (episode 29).

#Multi-Stage Builds

#Building a Static Application

FROM node:20-alpine AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
 
FROM caddy:2-alpine
COPY --from=build /app/dist /srv
COPY Caddyfile /etc/caddy/Caddyfile

#Caddyfile for an Application in the Image

:80 {
    root * /srv
    try_files {path} /index.html
    file_server
}

#Docker Compose

#A Complete Stack

services:
  caddy:
    image: caddy:2
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy_data:/data
      - caddy_config:/config
    networks:
      - web
 
  app:
    build: .
    networks:
      - web
 
  db:
    image: postgres:16
    networks:
      - web
 
volumes:
  caddy_data:
  caddy_config:
 
networks:
  web:

#Caddyfile for Compose

On a shared network, the service name becomes the hostname:

app.example.com {
    reverse_proxy app:3000
}

#Persistence and Configuration

#Volumes for Certificates

The caddy_data volume stores ACME certificates. If the volume is lost, Caddy requests certificates again — which can hit CA rate limits. Make sure:

• The volume is persistent (a named volume or bind mount).
• The volume is backed up periodically.
• Don't share one volume between competing instances (episode 16).

#Config Reload in a Container

docker exec caddy caddy reload --config /etc/caddy/Caddyfile

docker exec caddy caddy reload runs the command inside the container — a seamless reload. Or simply restart the container; Caddy reads the Caddyfile on start.

#Logs to stdout

The official Caddy image sends logs to stdout/stderr. Docker captures them automatically:

docker logs -f caddy

#Service Discovery and Common Patterns

#A Reverse Proxy for Many Applications

api.example.com {
    reverse_proxy api:3000
}
 
web.example.com {
    reverse_proxy web:3000
}
 
blog.example.com {
    root * /srv/blog
    file_server
}

#Container Name as Hostname

#Traefik vs Caddy in Docker

• Traefik is popular for Docker label-based automatic service discovery.
• Caddy is simpler: just a regular Caddyfile, and it can also use the caddy-docker-proxy plugin (episode 29) to manage via labels.

#Conclusion

Episode 27 covered Docker: the official image with persistent volumes, multi-stage builds for static applications, Docker Compose with a shared network, certificate persistence in caddy_data, service discovery via container names, and the one-Caddy-many-applications pattern.

Key takeaways:

• The caddy_data volume must be persistent for certificates.
• Multi-stage builds produce a compact Caddy image.
• Service names become hostnames in a Docker network.
• docker exec caddy caddy reload reloads without restart.
• Caddy logs go to stdout for docker logs.
• One Caddy can handle many applications at once.

In the next episode, episode 28, we'll cover Kubernetes deployment — Deployments, Services, ConfigMaps, and PersistentVolumeClaims, Caddy as an ingress, Caddyfile management in a ConfigMap, cert-manager integration, service discovery via K8s DNS, and Helm charts.