wemake-services/ caddy-gen

(0.3.0) over 1 year ago

Shell

Docker

proxy-server

caddy

caddy-plugin

View on GitHub

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

Readme

caddy-gen

Name: caddy-gen
Brand: caddy-gen
SKU: //wemake-services/caddy-gen
Rating: 2.1925 (177 reviews)

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 reverseproxy 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.

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

Changelog

Full changelog is available here.

License

MIT. See LICENSE for more details.