

Let's Encrypt¶

Automatic HTTPS

You can configure Traefik to use an ACME provider (like Let's Encrypt) for automatic certificate generation.

Let's Encrypt and Rate Limiting

Note that Let's Encrypt API has rate limiting.

Configuration Examples¶

Enabling ACME

File (TOML)

[entryPoints]
  [entryPoints.web]
    address = ":80"

  [entryPoints.web-secure]
    address = ":443"

[certificatesResolvers.sample.acme]
  email = "[email protected]"
  storage = "acme.json"
  [acme.httpChallenge]
    # used during the challenge
    entryPoint = "web"

File (YAML)

entryPoints:
  web:
    address: ":80"

  web-secure:
    address: ":443"

certificatesResolvers:
  sample:
    acme:
      email: [email protected]
      storage: acme.json
      httpChallenge:
        # used during the challenge
        entryPoint: web

CLI

--entryPoints.web.address=":80"
--entryPoints.websecure.address=":443"
# ...
--certificatesResolvers.sample.acme.email: [email protected]
--certificatesResolvers.sample.acme.storage: acme.json
# used during the challenge
--certificatesResolvers.sample.acme.httpChallenge.entryPoint: web

Configuration Reference

There are many available options for ACME. For a quick glance at what's possible, browse the configuration reference:

File (TOML)

# Enable ACME (Let's Encrypt): automatic SSL.
[certificatesResolvers.sample.acme]

  # Email address used for registration.
  #
  # Required
  #
  email = "[email protected]"

  # File or key used for certificates storage.
  #
  # Required
  #
  storage = "acme.json"

  # CA server to use.
  # Uncomment the line to use Let's Encrypt's staging server,
  # leave commented to go to prod.
  #
  # Optional
  # Default: "https://acme-v02.api.letsencrypt.org/directory"
  #
  # caServer = "https://acme-staging-v02.api.letsencrypt.org/directory"

  # KeyType to use.
  #
  # Optional
  # Default: "RSA4096"
  #
  # Available values : "EC256", "EC384", "RSA2048", "RSA4096", "RSA8192"
  #
  # keyType = "RSA4096"

  # Use a TLS-ALPN-01 ACME challenge.
  #
  # Optional (but recommended)
  #
  [certificatesResolvers.sample.acme.tlsChallenge]

  # Use a HTTP-01 ACME challenge.
  #
  # Optional
  #
  # [certificatesResolvers.sample.acme.httpChallenge]

    # EntryPoint to use for the HTTP-01 challenges.
    #
    # Required
    #
    # entryPoint = "web"

  # Use a DNS-01 ACME challenge rather than HTTP-01 challenge.
  # Note: mandatory for wildcard certificate generation.
  #
  # Optional
  #
  # [certificatesResolvers.sample.acme.dnsChallenge]

    # DNS provider used.
    #
    # Required
    #
    # provider = "digitalocean"

    # By default, the provider will verify the TXT DNS challenge record before letting ACME verify.
    # If delayBeforeCheck is greater than zero, this check is delayed for the configured duration in seconds.
    # Useful if internal networks block external DNS queries.
    #
    # Optional
    # Default: 0
    #
    # delayBeforeCheck = 0

    # Use following DNS servers to resolve the FQDN authority.
    #
    # Optional
    # Default: empty
    #
    # resolvers = ["1.1.1.1:53", "8.8.8.8:53"]

    # Disable the DNS propagation checks before notifying ACME that the DNS challenge is ready.
    #
    # NOT RECOMMENDED:
    # Increase the risk of reaching Let's Encrypt's rate limits.
    #
    # Optional
    # Default: false
    #
    # disablePropagationCheck = true

File (YAML)

certificatesResolvers:
  sample:
    # Enable ACME (Let's Encrypt): automatic SSL.
    acme:

      # Email address used for registration.
      #
      # Required
      #
      email: "[email protected]"

      # File or key used for certificates storage.
      #
      # Required
      #
      storage: "acme.json"

      # CA server to use.
      # Uncomment the line to use Let's Encrypt's staging server,
      # leave commented to go to prod.
      #
      # Optional
      # Default: "https://acme-v02.api.letsencrypt.org/directory"
      #
      # caServer: "https://acme-staging-v02.api.letsencrypt.org/directory"

      # KeyType to use.
      #
      # Optional
      # Default: "RSA4096"
      #
      # Available values : "EC256", "EC384", "RSA2048", "RSA4096", "RSA8192"
      #
      # keyType: RSA4096

      # Use a TLS-ALPN-01 ACME challenge.
      #
      # Optional (but recommended)
      #
      tlsChallenge:

      # Use a HTTP-01 ACME challenge.
      #
      # Optional
      #
      # httpChallenge:

        # EntryPoint to use for the HTTP-01 challenges.
        #
        # Required
        #
        # entryPoint: web

      # Use a DNS-01 ACME challenge rather than HTTP-01 challenge.
      # Note: mandatory for wildcard certificate generation.
      #
      # Optional
      #
      # dnsChallenge:

        # DNS provider used.
        #
        # Required
        #
        # provider: digitalocean

        # By default, the provider will verify the TXT DNS challenge record before letting ACME verify.
        # If delayBeforeCheck is greater than zero, this check is delayed for the configured duration in seconds.
        # Useful if internal networks block external DNS queries.
        #
        # Optional
        # Default: 0
        #
        # delayBeforeCheck: 0

        # Use following DNS servers to resolve the FQDN authority.
        #
        # Optional
        # Default: empty
        #
        # resolvers
        # - "1.1.1.1:53"
        # - "8.8.8.8:53"

        # Disable the DNS propagation checks before notifying ACME that the DNS challenge is ready.
        #
        # NOT RECOMMENDED:
        # Increase the risk of reaching Let's Encrypt's rate limits.
        #
        # Optional
        # Default: false
        #
        # disablePropagationCheck: true

CLI

# Enable ACME (Let's Encrypt): automatic SSL.

# Email address used for registration.
#
# Required
#
--certificatesResolvers.sample.acme.email="[email protected]"

# File or key used for certificates storage.
#
# Required
#
--certificatesResolvers.sample.acme.storage="acme.json"

# CA server to use.
# Uncomment the line to use Let's Encrypt's staging server,
# leave commented to go to prod.
#
# Optional
# Default: "https://acme-v02.api.letsencrypt.org/directory"
#
--certificatesResolvers.sample.acme.caServer="https://acme-staging-v02.api.letsencrypt.org/directory"

# KeyType to use.
#
# Optional
# Default: "RSA4096"
#
# Available values : "EC256", "EC384", "RSA2048", "RSA4096", "RSA8192"
#
--certificatesResolvers.sample.acme.keyType=RSA4096

# Use a TLS-ALPN-01 ACME challenge.
#
# Optional (but recommended)
#
--certificatesResolvers.sample.acme.tlsChallenge=true

# Use a HTTP-01 ACME challenge.
#
# Optional
#
--certificatesResolvers.sample.acme.httpChallenge=true

# EntryPoint to use for the HTTP-01 challenges.
#
# Required
#
--certificatesResolvers.sample.acme.httpChallenge.entryPoint=web

# Use a DNS-01 ACME challenge rather than HTTP-01 challenge.
# Note: mandatory for wildcard certificate generation.
#
# Optional
#
--certificatesResolvers.sample.acme.dnsChallenge=true

# DNS provider used.
#
# Required
#
--certificatesResolvers.sample.acme.dnsChallenge.provider=digitalocean

# By default, the provider will verify the TXT DNS challenge record before letting ACME verify.
# If delayBeforeCheck is greater than zero, this check is delayed for the configured duration in seconds.
# Useful if internal networks block external DNS queries.
#
# Optional
# Default: 0
#
--certificatesResolvers.sample.acme.dnsChallenge.delayBeforeCheck=0

# Use following DNS servers to resolve the FQDN authority.
#
# Optional
# Default: empty
#
--certificatesResolvers.sample.acme.dnsChallenge.resolvers="1.1.1.1:53,8.8.8.8:53"

# Disable the DNS propagation checks before notifying ACME that the DNS challenge is ready.
#
# NOT RECOMMENDED:
# Increase the risk of reaching Let's Encrypt's rate limits.
#
# Optional
# Default: false
#
--certificatesResolvers.sample.acme.dnsChallenge.disablePropagationCheck=true

Automatic Renewals¶

Traefik automatically tracks the expiry date of ACME certificates it generates.

If there are less than 30 days remaining before the certificate expires, Traefik will attempt to renew it automatically.

Note

Certificates that are no longer used may still be renewed, as Traefik does not currently check if the certificate is being used before renewing.

The Different ACME Challenges¶

`tlsChallenge`¶

Use the TLS-ALPN-01 challenge to generate and renew ACME certificates by provisioning a TLS certificate.

As described on the Let's Encrypt community forum, when using the TLS-ALPN-01 challenge, Traefik must be reachable by Let's Encrypt through port 443.

Configuring the tlsChallenge

File (TOML)

[certificatesResolvers.sample.acme]
  # ...
  [certificatesResolvers.sample.acme.tlsChallenge]

File (YAML)

certificatesResolvers:
  sample:
    acme:
      # ...
      tlsChallenge: {}

CLI

# ...
--certificatesResolvers.sample.acme.tlsChallenge=true

`httpChallenge`¶

Use the HTTP-01 challenge to generate and renew ACME certificates by provisioning an HTTP resource under a well-known URI.

As described on the Let's Encrypt community forum, when using the HTTP-01 challenge, certificatesResolvers.sample.acme.httpChallenge.entryPoint must be reachable by Let's Encrypt through port 80.

Using an EntryPoint Called http for the httpChallenge

File (TOML)

[entryPoints]
  [entryPoints.web]
    address = ":80"

  [entryPoints.web-secure]
    address = ":443"

[certificatesResolvers.sample.acme]
  # ...
  [certificatesResolvers.sample.acme.httpChallenge]
    entryPoint = "web"

File (YAML)

entryPoints:
  web:
    address: ":80"

  web-secure:
    address: ":443"

certificatesResolvers:
  sample:
    acme:
      # ...
      httpChallenge:
        entryPoint: web

CLI

--entryPoints.web.address=":80"
--entryPoints.websecure.address=":443"
# ...
--certificatesResolvers.sample.acme.httpChallenge.entryPoint=web

Note

Redirection is fully compatible with the HTTP-01 challenge.

`dnsChallenge`¶

Use the DNS-01 challenge to generate and renew ACME certificates by provisioning a DNS record.

Configuring a dnsChallenge with the DigitalOcean Provider

File (TOML)

[certificatesResolvers.sample.acme]
  # ...
  [certificatesResolvers.sample.acme.dnsChallenge]
    provider = "digitalocean"
    delayBeforeCheck = 0
# ...

File (YAML)

certificatesResolvers:
  sample:
    acme:
      # ...
      dnsChallenge:
        provider: digitalocean
        delayBeforeCheck: 0
    # ...

CLI

# ...
--certificatesResolvers.sample.acme.dnsChallenge.provider=digitalocean
--certificatesResolvers.sample.acme.dnsChallenge.delayBeforeCheck=0
# ...

Important

A provider is mandatory.

`providers`¶

Here is a list of supported providers, that can automate the DNS verification, along with the required environment variables and their wildcard & root domain support. Do not hesitate to complete it.

Every lego environment variable can be overridden by their respective _FILE counterpart, which should have a filepath to a file that contains the secret as its value. For example, CF_API_EMAIL_FILE=/run/secrets/traefik_cf-api-email could be used to provide a Cloudflare API email address as a Docker secret named traefik_cf-api-email.

Provider Name	Provider Code	Environment Variables
ACME DNS	`acme-dns`	`ACME_DNS_API_BASE`, `ACME_DNS_STORAGE_PATH`	Additional configuration
Alibaba Cloud	`alidns`	`ALICLOUD_ACCESS_KEY`, `ALICLOUD_SECRET_KEY`, `ALICLOUD_REGION_ID`	Additional configuration
Auroradns	`auroradns`	`AURORA_USER_ID`, `AURORA_KEY`, `AURORA_ENDPOINT`	Additional configuration
Azure	`azure`	`AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`, `AZURE_SUBSCRIPTION_ID`, `AZURE_TENANT_ID`, `AZURE_RESOURCE_GROUP`, `[AZURE_METADATA_ENDPOINT]`	Additional configuration
Blue Cat	`bluecat`	`BLUECAT_SERVER_URL`, `BLUECAT_USER_NAME`, `BLUECAT_PASSWORD`, `BLUECAT_CONFIG_NAME`, `BLUECAT_DNS_VIEW`	Additional configuration
ClouDNS	`cloudns`	`CLOUDNS_AUTH_ID`, `CLOUDNS_AUTH_PASSWORD`	Additional configuration
Cloudflare	`cloudflare`	`CF_API_EMAIL`, `CF_API_KEY` - The `Global API Key` needs to be used, not the `Origin CA Key`	Additional configuration
CloudXNS	`cloudxns`	`CLOUDXNS_API_KEY`, `CLOUDXNS_SECRET_KEY`	Additional configuration
ConoHa	`conoha`	`CONOHA_TENANT_ID`, `CONOHA_API_USERNAME`, `CONOHA_API_PASSWORD`	Additional configuration
DigitalOcean	`digitalocean`	`DO_AUTH_TOKEN`	Additional configuration
DNSimple	`dnsimple`	`DNSIMPLE_OAUTH_TOKEN`, `DNSIMPLE_BASE_URL`	Additional configuration
DNS Made Easy	`dnsmadeeasy`	`DNSMADEEASY_API_KEY`, `DNSMADEEASY_API_SECRET`, `DNSMADEEASY_SANDBOX`	Additional configuration
DNSPod	`dnspod`	`DNSPOD_API_KEY`	Additional configuration
Domain Offensive (do.de)	`dode`	`DODE_TOKEN`	Additional configuration
DreamHost	`dreamhost`	`DREAMHOST_API_KEY`	Additional configuration
Duck DNS	`duckdns`	`DUCKDNS_TOKEN`	Additional configuration
Dyn	`dyn`	`DYN_CUSTOMER_NAME`, `DYN_USER_NAME`, `DYN_PASSWORD`	Additional configuration
External Program	`exec`	`EXEC_PATH`	Additional configuration
Exoscale	`exoscale`	`EXOSCALE_API_KEY`, `EXOSCALE_API_SECRET`, `EXOSCALE_ENDPOINT`	Additional configuration
Fast DNS	`fastdns`	`AKAMAI_CLIENT_TOKEN`, `AKAMAI_CLIENT_SECRET`, `AKAMAI_ACCESS_TOKEN`	Additional configuration
Gandi	`gandi`	`GANDI_API_KEY`	Additional configuration
Gandi v5	`gandiv5`	`GANDIV5_API_KEY`	Additional configuration
Glesys	`glesys`	`GLESYS_API_USER`, `GLESYS_API_KEY`, `GLESYS_DOMAIN`	Additional configuration
GoDaddy	`godaddy`	`GODADDY_API_KEY`, `GODADDY_API_SECRET`	Additional configuration
Google Cloud DNS	`gcloud`	`GCE_PROJECT`, Application Default Credentials ² ³, [`GCE_SERVICE_ACCOUNT_FILE`]	Additional configuration
hosting.de	`hostingde`	`HOSTINGDE_API_KEY`, `HOSTINGDE_ZONE_NAME`	Additional configuration
HTTP request	`httpreq`	`HTTPREQ_ENDPOINT`, `HTTPREQ_MODE`, `HTTPREQ_USERNAME`, `HTTPREQ_PASSWORD` ¹	Additional configuration
IIJ	`iij`	`IIJ_API_ACCESS_KEY`, `IIJ_API_SECRET_KEY`, `IIJ_DO_SERVICE_CODE`	Additional configuration
INWX	`inwx`	`INWX_USERNAME`, `INWX_PASSWORD`	Additional configuration
Lightsail	`lightsail`	`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `DNS_ZONE`	Additional configuration
Linode	`linode`	`LINODE_API_KEY`	Additional configuration
Linode v4	`linodev4`	`LINODE_TOKEN`	Additional configuration
manual	-	none, but you need to run Traefik interactively ⁴, turn on debug log to see instructions and press `Enter`.
MyDNS.jp	`mydnsjp`	`MYDNSJP_MASTER_ID`, `MYDNSJP_PASSWORD`	Additional configuration
Namecheap	`namecheap`	`NAMECHEAP_API_USER`, `NAMECHEAP_API_KEY`	Additional configuration
name.com	`namedotcom`	`NAMECOM_USERNAME`, `NAMECOM_API_TOKEN`, `NAMECOM_SERVER`	Additional configuration
Netcup	`netcup`	`NETCUP_CUSTOMER_NUMBER`, `NETCUP_API_KEY`, `NETCUP_API_PASSWORD`	Additional configuration
NIFCloud	`nifcloud`	`NIFCLOUD_ACCESS_KEY_ID`, `NIFCLOUD_SECRET_ACCESS_KEY`	Additional configuration
Ns1	`ns1`	`NS1_API_KEY`	Additional configuration
Open Telekom Cloud	`otc`	`OTC_DOMAIN_NAME`, `OTC_USER_NAME`, `OTC_PASSWORD`, `OTC_PROJECT_NAME`, `OTC_IDENTITY_ENDPOINT`	Additional configuration
OVH	`ovh`	`OVH_ENDPOINT`, `OVH_APPLICATION_KEY`, `OVH_APPLICATION_SECRET`, `OVH_CONSUMER_KEY`	Additional configuration
Openstack Designate	`designate`	`OS_AUTH_URL`, `OS_USERNAME`, `OS_PASSWORD`, `OS_TENANT_NAME`, `OS_REGION_NAME`	Additional configuration
Oracle Cloud	`oraclecloud`	`OCI_COMPARTMENT_OCID`, `OCI_PRIVKEY_FILE`, `OCI_PRIVKEY_PASS`, `OCI_PUBKEY_FINGERPRINT`, `OCI_REGION`, `OCI_TENANCY_OCID`, `OCI_USER_OCID`	Additional configuration
PowerDNS	`pdns`	`PDNS_API_KEY`, `PDNS_API_URL`	Additional configuration
Rackspace	`rackspace`	`RACKSPACE_USER`, `RACKSPACE_API_KEY`	Additional configuration
RFC2136	`rfc2136`	`RFC2136_TSIG_KEY`, `RFC2136_TSIG_SECRET`, `RFC2136_TSIG_ALGORITHM`, `RFC2136_NAMESERVER`	Additional configuration
Route 53	`route53`	`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `[AWS_REGION]`, `[AWS_HOSTED_ZONE_ID]` or a configured user/instance IAM profile.	Additional configuration
Sakura Cloud	`sakuracloud`	`SAKURACLOUD_ACCESS_TOKEN`, `SAKURACLOUD_ACCESS_TOKEN_SECRET`	Additional configuration
Selectel	`selectel`	`SELECTEL_API_TOKEN`	Additional configuration
Stackpath	`stackpath`	`STACKPATH_CLIENT_ID`, `STACKPATH_CLIENT_SECRET`, `STACKPATH_STACK_ID`	Additional configuration
TransIP	`transip`	`TRANSIP_ACCOUNT_NAME`, `TRANSIP_PRIVATE_KEY_PATH`	Additional configuration
VegaDNS	`vegadns`	`SECRET_VEGADNS_KEY`, `SECRET_VEGADNS_SECRET`, `VEGADNS_URL`	Additional configuration
Vscale	`vscale`	`VSCALE_API_TOKEN`	Additional configuration
VULTR	`vultr`	`VULTR_API_KEY`	Additional configuration
Zone.ee	`zoneee`	`ZONEEE_API_USER`, `ZONEEE_API_KEY`	Additional configuration

delayBeforeCheck

By default, the provider verifies the TXT record before letting ACME verify. You can delay this operation by specifying a delay (in seconds) with delayBeforeCheck (value must be greater than zero). This option is useful when internal networks block external DNS queries.

`resolvers`¶

Use custom DNS servers to resolve the FQDN authority.

File (TOML)

[certificatesResolvers.sample.acme]
  # ...
  [certificatesResolvers.sample.acme.dnsChallenge]
    # ...
    resolvers = ["1.1.1.1:53", "8.8.8.8:53"]

File (YAML)

certificatesResolvers:
  sample:
    acme:
      # ...
      dnsChallenge:
        # ...
        resolvers:
        - "1.1.1.1:53"
        - "8.8.8.8:53"

CLI

# ...
--certificatesResolvers.sample.acme.dnsChallenge.resolvers:="1.1.1.1:53,8.8.8.8:53"

Wildcard Domains¶

ACME V2 supports wildcard certificates. As described in Let's Encrypt's post wildcard certificates can only be generated through a DNS-01 challenge.

`caServer`¶

Using the Let's Encrypt staging server

File (TOML)

[certificatesResolvers.sample.acme]
  # ...
  caServer = "https://acme-staging-v02.api.letsencrypt.org/directory"
  # ...

File (YAML)

certificatesResolvers:
  sample:
    acme:
      # ...
      caServer: https://acme-staging-v02.api.letsencrypt.org/directory
      # ...

CLI

# ...
--certificatesResolvers.sample.acme.caServer="https://acme-staging-v02.api.letsencrypt.org/directory"
# ...

`storage`¶

The storage option sets the location where your ACME certificates are saved to.

File (TOML)

[certificatesResolvers.sample.acme]
  # ...
  storage = "acme.json"
  # ...

File (YAML)

certificatesResolvers:
  sample:
    acme:
      # ...
      storage: acme.json
      # ...

CLI

# ...
--certificatesResolvers.sample.acme.storage=acme.json
# ...

The value can refer to some kinds of storage:

a JSON file

In a File¶

ACME certificates can be stored in a JSON file that needs to have a 600 file mode .

In Docker you can mount either the JSON file, or the folder containing it:

docker run -v "/my/host/acme.json:acme.json" traefik

docker run -v "/my/host/acme:/etc/traefik/acme" traefik

Warning

For concurrency reason, this file cannot be shared across multiple instances of Traefik. Use a key value store entry instead.

Fallback¶

If Let's Encrypt is not reachable, the following certificates will apply:

Previously generated ACME certificates (before downtime)
Expired ACME certificates
Provided certificates

Note

For new (sub)domains which need Let's Encrypt authentication, the default Traefik certificate will be used until Traefik is restarted.

more information about the HTTP message format can be found here ↩
providing_credentials_to_your_application ↩
google/default.go ↩
docker stack remark: there is no way to support terminal attached to container when deploying with docker stack, so you might need to run container with docker run -it to generate certificates using manual provider. ↩

Let's Encrypt¶

Configuration Examples¶

Automatic Renewals¶

The Different ACME Challenges¶

tlsChallenge¶

httpChallenge¶

dnsChallenge¶

providers¶

resolvers¶

Wildcard Domains¶

caServer¶

storage¶

In a File¶

Fallback¶

`tlsChallenge`¶

`httpChallenge`¶

`dnsChallenge`¶

`providers`¶

`resolvers`¶

`caServer`¶

`storage`¶