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!

CADDY 2

BREAKING CHANGES since version 0.3.0!

Options to configure:

• virtual.host domain name, don't pass http:// or https://, you can separate them with space,
• virtual.alias domain alias, e.q. www prefix,
• virtual.port port exposed by container, e.g. 3000 for React apps in development,
• virtual.tls-email the email address to use for the ACME account managing the site's certificates,
• virtual.auth.path with
• virtual.auth.username and
• virtual.auth.password together provide HTTP basic authentication.

Password should be a string base64 encoded from bcrypt hash. You can use https://bcrypt-generator.com/ with default config and https://www.base64encode.org/.

Backing up certificates

To backup certificates make a volume:

services:
  caddy:
    volumes:
      - ./caddy-info:/data/caddy

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
      - ./caddy-info:/data/caddy # needs volume to back up 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" # your domain
      - "virtual.alias=www.myapp.com" # alias for your domain (optional)
      - "virtual.port=80" # exposed port of this container
      - "[email protected]" # ssl is now on
      - "virtual.auth.path=/secret/*" # path basic authnetication applys to
      - "virtual.auth.username=admin" # Optionally add http basic authentication
      - "virtual.auth.password=JDJ5JDEyJEJCdzJYM0pZaWtMUTR4UVBjTnRoUmVJeXQuOC84QTdMNi9ONnNlbDVRcHltbjV3ME1pd2pLCg==" # By specifying both username and password hash

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.auth.username when set, along with virtual.auth.password and virtual.auth.path, http basic authentication is enabled
• virtual.auth.password needs to be specified, along with virtual.auth.usernmae, to enable http basic authentication
• virtual.auth.path sets path basic auth applys to.

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

Backing up certificates

To backup certificates make a volume:

services:
  caddy:
    volumes:
      - ./caddy-info:/data/caddy

Versions

This image supports two build-time arguments:

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

See also

• Raw Caddy image
• Django project template with Caddy
• Tool to limit your docker image size

Changelog

Full changelog is available here.

License

MIT. See LICENSE for more details.