caddy-gen

A perfect mix of Caddy, docker-gen, and forego. Inspired by nginx-proxy.

Why

Using Caddy as your primary web server is super simple. But when you need to scale your application Caddy is limited to its static configuration.

To overcome this issue we are using docker-gen to generate configuration everytime a container spawns or dies. Now scaling is easy!

Usage

This image is created to be used in a single container.

version: "3"
services:
  caddy-gen:
    container_name: caddy-gen
    image: "wemakeservices/caddy-gen:latest"
    restart: always
    volumes:
      - /var/run/docker.sock:/tmp/docker.sock:ro  # needs socket to read events
      - ./certs/acme:/etc/caddy/acme  # to save acme
      - ./certs/ocsp:/etc/caddy/ocsp  # to save certificates
    ports:
      - "80:80"
      - "443:443"
    depends_on:
      - whoami

  whoami:  # this is your service
    image: "katacoda/docker-http-server:v2"
    labels:
      - "virtual.host=myapp.com example.com"  # your domains separated with a space
      - "virtual.alias=www.myapp.com"  # alias for your domain (optional)
      - "virtual.port=80"  # exposed port of this container
      - "virtual.tls-email=admin@myapp.com"  # ssl is now on
      - "virtual.websockets" # enable websocket passthrough
      - "virtual.auth.username=admin" # Optionally add http basic authentication
      - "virtual.auth.password=1234" # By specifying both username and password

Or see docker-compose.yml example file.

Configuration

caddy-gen is configured with labels.

The main idea is simple. Every labeled service exposes a virtual.host to be handled. Then, every container represents a single upstream to serve requests.

There are several options to configure:

virtual.host is basically a domain name, see Caddy docs
virtual.alias (optional) domain alias, useful for www prefix with redirect. For example www.myapp.com. Alias will always redirect to the host above.
virtual.port exposed port of the container
virtual.tls-email could be empty, unset or set to valid email
virtual.tls (alias of virtual.tls-email) could be empty, unset or set to a valid set of tls directive value(s)
virtual.websocket when set, enables websocket connection passthrough
virtual.auth.username when set, along with virtual.auth.password, http basic authentication is enabled
virtual.auth.password needs to be specified, along with virtual.auth.usernmae, to enable http basic authentication

Note, that options should not differ for containers of a single service.

Backing up certificates

Certificates are stored in /etc/caddy/acme/ and /etc/caddy/ocsp folders. Make them volumes to save them on your host machine.

Versions

This image supports three build-time arguments:

CADDY_VERSION to change the current version of Caddy
FOREGO_VERSION to change the current version of forego
DOCKER_GEN_VERSION to change the current version of docker-gen

Changelog

Full changelog is available here.

License

MIT. See LICENSE for more details.

amedranogil/caddy-gen