SSL

Generating Wildcard SSL Certificate

A wildcard certificate (*.example.com) will be the default.

To change this, see Changing SSL Certificate SANs. Note that an individual certificate for each container will not be generated due to Let’s Encrypts rate limit of 5 exact hostnames every 7 days.

Requirements

• A supported DNS provider (e.g. Cloudflare), you can find supported providers here along with their settings
  • You will need to click on your provider and retrieve the Code: at the top and the correct Environment Variable Names
• A valid Top-Level Domain (TLD), such as .com or .net, that Let’s Encrypt is able to issue certificates for
• API keys for the DNS provider with the correct permissions
  • If using Cloudflare, it needs Zone.DNS:Edit permissions for the correct zone. This can be the same key for Cloudflare DDNS in this project

Tip

The default configuration already has the correct Environment Variables for Cloudflare.

If also using Cloudflare, set the API key in cloudflare_api_token in inventory/group_vars/all/cloudflare.yml:

inventory/group_vars/all/cloudflare.yml

cloudflare_api_token: <token>

Configuration

Settings mentioned below should already exist in your inventory/group_vars/all/traefik.yml:

inventory/group_vars/all/traefik.yml

traefik_ssl_enabled: true                     # whether or not to generate a wildcard SSL certificate
traefik_ssl_dns_provider_zone:                # the zone of the DNS provider (e.g. `example.com`, this will default to the `hms_docker_domain` if not modified)
traefik_ssl_dns_provider_code:                # the "Provider Code" of the DNS provider (e.g. `cloudflare`, found at link above)
traefik_ssl_dns_provider_environment_vars: [  # the "Environment Variables", along with their values, of the DNS provider you're using (e.g. `"CF_DNS_API_TOKEN": "<token>"` if using `cloudflare`, found at link above)
  "ENVIRONMENT_VARIABLE_NAME": "ENVIRONMENT_VARIABLE_VALUE",
  ...
]
traefik_ssl_letsencrypt_email:                # the email address to use for Let's Encrypt
traefik_ssl_use_letsencrypt_staging_url: true # whether or not to use the Let's Encrypt staging URL for initial testing (`yes` or `no`) (default: `yes`)

First Time Test

For the first time generating a certificate, it is recommended to use the staging URL (by configuring above) so you do not encounter Rate-Limiting from Let’s Encrypt

The certificate will say it is invalid within a browser, but if you check the issuer, it should come from the “Staging” server, meaning it worked successfully and you then change this value to no to use the production server and get a valid certificate.

Note

Once the playbook has finished running, it may take up to a few minutes for the SSL certificate to be generated.

To view debug logs, set traefik_log_level to DEBUG and then re-run the playbook and run docker logs traefik -f. This can show you the status of the certificate generation request.

Changing SSL Certificate SANs

To change/add the SANs (Subject Alternative Name) used for the certificate, in inventory/group_vars/all/traefik.yml modify the traefik_ssl_sans variable.

By default, it will generate a wildcard certificate for the domain set in hms_docker_domain.

Here’s an example of adding an additional *.dev.<domain> SAN to the certificate:

inventory/group_vars/all/traefik.yml

traefik_ssl_sans: [
  '*.{{ hms_docker_domain }}',
  '*.dev.{{ hms_docker_domain }}'
]