Need help with caddy-gen?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

wemake-services
177 Stars 21 Forks MIT License 70 Commits 9 Opened issues

Description

Automated Caddy reverse proxy for docker containers

Services available

!
?

Need anything else?

Contributors list

caddy-gen

wemake.services Build Status Dockerhub image size caddy's version

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!

Configuration / Options

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.

NOTE: Caddy2 was introduced in version 0.3.0 causing BREAKING CHANGES.

Main configuration options:

  • virtual.host
    (required) domain name, don't pass
    http://
    or
    https://
    , you can separate them with spaces.
  • virtual.alias
    domain alias, useful for
    www
    prefix with redirect. For example
    www.myapp.com
    . Alias will always redirect to the host above.
  • 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 (required to enable HTTPS).
  • virtual.tls
    alias of
    virtual.tls-email
    .
  • virtual.host.directives
    set custom Caddyfile directives for the host. These will be inlined into the site block.
  • virtual.host.import
    include Caddyfile directives for the host from a file on the container's filesystem. See Caddy import.

Basic authentication options: -

virtual.auth.path
with -
virtual.auth.username
and -
virtual.auth.password
together enable 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/.)

Reverse proxy options: -

virtual.proxy.matcher
have the reverse proxy only match certain paths. -
virtual.proxy.lb_policy
specify load balancer policy, defaults to
round_robin
. -
virtual.proxy.directives
include any reverseproxy directives. These will be inlined into the reverse proxy block. -
virtual.proxy.import
include any reverse
proxy directives from a file on the container's filesystem. See Caddy import.

To include a custom template: - mount a volume containing your custom template and/or snippet (they both may be Go templates and will be loaded by

docker-gen
). - set the environment variable
CADDY_TEMPLATE
to the mounted file containining your custom Caddyfile template. This will replace the default template. - set the environment variable
CADDY_SNIPPET
to the mounted file containining your custom Caddyfile snippet. This will be prepended to the caddy template, so you may use it to set Global Options, define snippet blocks, or add custom address blocks. - See example "Use a custom Caddy template for
docker-gen
"

Version build-time arguments

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

Usage

Caddy-gen is created to be used in a single container. It will act as a reverse proxy for the whoami service.

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 authentication applies to - "virtual.auth.username=admin" # Optionally add http basic authentication - "virtual.auth.password=JDJ5JDEyJEJCdzJYM0pZaWtMUTR4UVBjTnRoUmVJeXQuOC84QTdMNi9ONnNlbDVRcHltbjV3ME1pd2pLCg==" # By specifying both username and password hash

See

docker-compose.yml
example file.

Backing up certificates

To backup certificates make a volume:

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

Add or modify reverse_proxy headers

With the following settings, the upstream host will see its own address instead of the original incoming value. See Headers.

version: "3"
services:
  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: image: "katacoda/docker-http-server:v2" labels: virtual.host: myapp.com virtual.port: 80 virtual.tls: [email protected] virtual.proxy.directives: | header_up Host {http.reverse_proxy.upstream.hostport}

Set up a static file server for a host

With the following settings, myapp.com will serve files from directory

www
and only requests to
/api/*
will be routed to the whoami service. See file_server.
version: "3"
services:
  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
      - ./www:/srv/myapp/www # files served by myapp.com
    ports:
      - "80:80"
      - "443:443"
    depends_on:
      - whoami

whoami: image: "katacoda/docker-http-server:v2" labels: virtual.host: myapp.com virtual.port: 80 virtual.tls: [email protected] virtual.proxy.matcher: /api/* virtual.host.directives: | root * /srv/myapp/www templates file_server

Use a custom Caddy template for
docker-gen

With this custom template, Caddy-gen will act as a reverse proxy for service containers and store their logs under the appropriate host folder in

/var/logs
.
# file: ./caddy/template
(redirectHttps) {
  @http {
    protocol http
  }
  redir @http https://{host}{uri}
}

(logFile) { log { output file /var/caddy/{host}/logs { roll_keep_for 7 } } }

{{ $hosts := groupByLabel $ "virtual.host" }} {{ range $h, $containers := $hosts }} {{ range $t, $host := split (trim (index $c.Labels "virtual.host")) " " }} {{ $tls = trim (index $c.Labels "virtual.tls") }} {{ $host }} { {{ if $tls }} tls {{ $tls }} import redirectHttps {{ end }} reverse_proxy { lb_policy round_robin {{ range $i, $container := $containers }} {{ range $j, $net := $container.Networks }} to {{ $net.IP}}:{{ or (trim (index $container.Labels "virtual.port")) "80" }} {{ end }} {{ end }} } encode zstd gzip import logFile }

# file: docker-compose.yml
services:
  caddy-gen:
    volumes:
      # mount the template file into the container
      - ./caddy/template:/tmp/caddy/template
    environment:
      # CADDY_TEMPLATE will replace the default caddy template
      CADDY_TEMPLATE: /tmp/caddy/template

Set global options for Caddy

With this snippet, Caddy will request SSL certificates from the Let's Encrypt staging environment. This is useful for testing without running up against rate limits when you want to deploy.

# file: ./caddy/global_options
{
  acme_ca https://acme-staging-v02.api.letsencrypt.org/directory
}
# file: docker-compose.yml
services:
  caddy-gen:
    volumes:
      # mount the template file into the container
      - ./caddy/global_options:/tmp/caddy/global_options
    environment:
      # CADDY_SNIPPET will prepend to the default caddy template
      CADDY_SNIPPET: /tmp/caddy/global_options

See also

Changelog

Full changelog is available here.

License

MIT. See LICENSE for more details.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.