Custom SSL/TLS certificates #

By default, Caddy uses Let’s Encrypt to generate certificates. This guide explains how to supply your own or override this default behavior.

Custom ACME server #

To set global Caddy directives, prefix the directive with caddy., but ensure to omit a domain or reverse_proxy directive. See the dashboard example for more.

To override Caddy’s (global) Let’s Encrypt settings for e.g. the Austrian-based ZeroSSL, you can use the following set of labels on your Caddy deployment:

deploy:
  labels:
    caddy.acme_ca: "https://acme.zerossl.com/v2/DV90"

Or on a site-basis (using EAB-credentials):

deploy:
  labels:
    caddy: "example.org"
    caddy.reverse_proxy: "{{upstreams 80}}"
    caddy.tls.issuer: "acme"
    caddy.tls.issuer.dir: "https://acme.zerossl.com/v2/DV90"
    caddy.tls.issuer.eab.key_id: "YOUR_ZEROSSL_EAB_KEY_ID"
    caddy.tls.issuer.eab.mac_key: "YOUR_ZEROSSL_EAB_HMAC_KEY"

The traditional method #

This stores a custom SSL cert in /etc/caddy/certs inside the Caddy container.

Security: We suggest to map the /etc/caddy/certs directory to a volume or use the s3 storage backend instead of baking the certificate files and private keys into the container.

Once you generated your private key and purchased your certificate, you usually receive two files. Combine your server certificate and the bundle into a fullchain.pem:

cat server.crt bundle.pem > fullchain.pem

Proceed to upload the files to the volume and configure the stack like in the following example:

version: '3.8'

services:
  example:
    image: wordpress
    networks:
      - public
    deploy:
      labels:
        caddy: "example.org"
        caddy.reverse_proxy: "{{upstreams 80}}"
        caddy.tls: "/etc/caddy/certs/fullchain.pem /etc/caddy/certs/key.pem"

networks:
  public:
    external: true
    name: public