A perfect mix of Caddy
, docker-gen
, and forego
. Inspired by nginx-proxy
.
Download:
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-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 passhttp://
orhttps://
, you can separate them with spaces.virtual.alias
domain alias, useful forwww
prefix with redirect. For examplewww.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 ofvirtual.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
withvirtual.auth.username
andvirtual.auth.password
together enable HTTP basic authentication. (Password should be a stringbase64
encoded frombcrypt
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 toround_robin
.virtual.proxy.directives
include any reverse_proxy 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
"
This image supports two build-time arguments:
FOREGO_VERSION
to change the current version offorego
DOCKER_GEN_VERSION
to change the current version ofdocker-gen
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 # or ghcr.io/wemake-services/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
- "virtual.tls-email=admin@myapp.com" # 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.
To backup certificates make a volume:
services:
caddy:
volumes:
- ./caddy-info:/data/caddy
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 # or ghcr.io/wemake-services/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: admin@myapp.com
virtual.proxy.directives: |
header_up Host {http.reverse_proxy.upstream.hostport}
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 # or ghcr.io/wemake-services/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: admin@myapp.com
virtual.proxy.matcher: /api/*
virtual.host.directives: |
root * /srv/myapp/www
templates
file_server
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
- Raw
Caddy
image - Django project template with
Caddy
- Tool to limit your
docker
image size
Full changelog is available here.
MIT. See LICENSE for more details.