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

  1. [entryPoints]
  2.   [entryPoints.web]
  3.     address = ":80"
  5.   [entryPoints.web-secure]
  6.     address = ":443"
  8. [certificatesResolvers.sample.acme]
  9.   email = "[email protected]"
  10.   storage = "acme.json"
  11.   [acme.httpChallenge]
  12.     # used during the challenge
  13.     entryPoint = "web"
  1. entryPoints:
  2.   web:
  3.     address: ":80"
  5.   web-secure:
  6.     address: ":443"
  8. certificatesResolvers:
  9.   sample:
  10.     acme:
  11.       email: [email protected]
  12.       storage: acme.json
  13.       httpChallenge:
  14.         # used during the challenge
  15.         entryPoint: web
  1. --entryPoints.web.address=":80"
  2. --entryPoints.websecure.address=":443"
  3. # ...
  4. --certificatesResolvers.sample.acme.email="[email protected]"
  5. --certificatesResolvers.sample.acme.storage="acme.json"
  6. # used during the challenge
  7. --certificatesResolvers.sample.acme.httpChallenge.entryPoint=web

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

  1. # Enable ACME (Let's Encrypt): automatic SSL.
  2. [certificatesResolvers.sample.acme]
  4.   # Email address used for registration.
  5.   #
  6.   # Required
  7.   #
  8.   email = "[email protected]"
  10.   # File or key used for certificates storage.
  11.   #
  12.   # Required
  13.   #
  14.   storage = "acme.json"
  16.   # CA server to use.
  17.   # Uncomment the line to use Let's Encrypt's staging server,
  18.   # leave commented to go to prod.
  19.   #
  20.   # Optional
  21.   # Default: "https://acme-v02.api.letsencrypt.org/directory"
  22.   #
  23.   # caServer = "https://acme-staging-v02.api.letsencrypt.org/directory"
  25.   # KeyType to use.
  26.   #
  27.   # Optional
  28.   # Default: "RSA4096"
  29.   #
  30.   # Available values : "EC256", "EC384", "RSA2048", "RSA4096", "RSA8192"
  31.   #
  32.   # keyType = "RSA4096"
  34.   # Use a TLS-ALPN-01 ACME challenge.
  35.   #
  36.   # Optional (but recommended)
  37.   #
  38.   [certificatesResolvers.sample.acme.tlsChallenge]
  40.   # Use a HTTP-01 ACME challenge.
  41.   #
  42.   # Optional
  43.   #
  44.   # [certificatesResolvers.sample.acme.httpChallenge]
  46.     # EntryPoint to use for the HTTP-01 challenges.
  47.     #
  48.     # Required
  49.     #
  50.     # entryPoint = "web"
  52.   # Use a DNS-01 ACME challenge rather than HTTP-01 challenge.
  53.   # Note: mandatory for wildcard certificate generation.
  54.   #
  55.   # Optional
  56.   #
  57.   # [certificatesResolvers.sample.acme.dnsChallenge]
  59.     # DNS provider used.
  60.     #
  61.     # Required
  62.     #
  63.     # provider = "digitalocean"
  65.     # By default, the provider will verify the TXT DNS challenge record before letting ACME verify.
  66.     # If delayBeforeCheck is greater than zero, this check is delayed for the configured duration in seconds.
  67.     # Useful if internal networks block external DNS queries.
  68.     #
  69.     # Optional
  70.     # Default: 0
  71.     #
  72.     # delayBeforeCheck = 0
  74.     # Use following DNS servers to resolve the FQDN authority.
  75.     #
  76.     # Optional
  77.     # Default: empty
  78.     #
  79.     # resolvers = ["1.1.1.1:53", "8.8.8.8:53"]
  81.     # Disable the DNS propagation checks before notifying ACME that the DNS challenge is ready.
  82.     #
  83.     # NOT RECOMMENDED:
  84.     # Increase the risk of reaching Let's Encrypt's rate limits.
  85.     #
  86.     # Optional
  87.     # Default: false
  88.     #
  89.     # disablePropagationCheck = true
  1. certificatesResolvers:
  2.   sample:
  3.     # Enable ACME (Let's Encrypt): automatic SSL.
  4.     acme:
  6.       # Email address used for registration.
  7.       #
  8.       # Required
  9.       #
  10.       email: "[email protected]"
  12.       # File or key used for certificates storage.
  13.       #
  14.       # Required
  15.       #
  16.       storage: "acme.json"
  18.       # CA server to use.
  19.       # Uncomment the line to use Let's Encrypt's staging server,
  20.       # leave commented to go to prod.
  21.       #
  22.       # Optional
  23.       # Default: "https://acme-v02.api.letsencrypt.org/directory"
  24.       #
  25.       # caServer: "https://acme-staging-v02.api.letsencrypt.org/directory"
  27.       # KeyType to use.
  28.       #
  29.       # Optional
  30.       # Default: "RSA4096"
  31.       #
  32.       # Available values : "EC256", "EC384", "RSA2048", "RSA4096", "RSA8192"
  33.       #
  34.       # keyType: RSA4096
  36.       # Use a TLS-ALPN-01 ACME challenge.
  37.       #
  38.       # Optional (but recommended)
  39.       #
  40.       tlsChallenge:
  42.       # Use a HTTP-01 ACME challenge.
  43.       #
  44.       # Optional
  45.       #
  46.       # httpChallenge:
  48.         # EntryPoint to use for the HTTP-01 challenges.
  49.         #
  50.         # Required
  51.         #
  52.         # entryPoint: web
  54.       # Use a DNS-01 ACME challenge rather than HTTP-01 challenge.
  55.       # Note: mandatory for wildcard certificate generation.
  56.       #
  57.       # Optional
  58.       #
  59.       # dnsChallenge:
  61.         # DNS provider used.
  62.         #
  63.         # Required
  64.         #
  65.         # provider: digitalocean
  67.         # By default, the provider will verify the TXT DNS challenge record before letting ACME verify.
  68.         # If delayBeforeCheck is greater than zero, this check is delayed for the configured duration in seconds.
  69.         # Useful if internal networks block external DNS queries.
  70.         #
  71.         # Optional
  72.         # Default: 0
  73.         #
  74.         # delayBeforeCheck: 0
  76.         # Use following DNS servers to resolve the FQDN authority.
  77.         #
  78.         # Optional
  79.         # Default: empty
  80.         #
  81.         # resolvers
  82.         # - "1.1.1.1:53"
  83.         # - "8.8.8.8:53"
  85.         # Disable the DNS propagation checks before notifying ACME that the DNS challenge is ready.
  86.         #
  87.         # NOT RECOMMENDED:
  88.         # Increase the risk of reaching Let's Encrypt's rate limits.
  89.         #
  90.         # Optional
  91.         # Default: false
  92.         #
  93.         # disablePropagationCheck: true
  1. # Enable ACME (Let's Encrypt): automatic SSL.
  3. # Email address used for registration.
  4. #
  5. # Required
  6. #
  7. --certificatesResolvers.sample.acme.email="[email protected]"
  9. # File or key used for certificates storage.
  10. #
  11. # Required
  12. #
  13. --certificatesResolvers.sample.acme.storage="acme.json"
  15. # CA server to use.
  16. # Uncomment the line to use Let's Encrypt's staging server,
  17. # leave commented to go to prod.
  18. #
  19. # Optional
  20. # Default: "https://acme-v02.api.letsencrypt.org/directory"
  21. #
  22. --certificatesResolvers.sample.acme.caServer="https://acme-staging-v02.api.letsencrypt.org/directory"
  24. # KeyType to use.
  25. #
  26. # Optional
  27. # Default: "RSA4096"
  28. #
  29. # Available values : "EC256", "EC384", "RSA2048", "RSA4096", "RSA8192"
  30. #
  31. --certificatesResolvers.sample.acme.keyType=RSA4096
  33. # Use a TLS-ALPN-01 ACME challenge.
  34. #
  35. # Optional (but recommended)
  36. #
  37. --certificatesResolvers.sample.acme.tlsChallenge=true
  39. # Use a HTTP-01 ACME challenge.
  40. #
  41. # Optional
  42. #
  43. --certificatesResolvers.sample.acme.httpChallenge=true
  45. # EntryPoint to use for the HTTP-01 challenges.
  46. #
  47. # Required
  48. #
  49. --certificatesResolvers.sample.acme.httpChallenge.entryPoint=web
  51. # Use a DNS-01 ACME challenge rather than HTTP-01 challenge.
  52. # Note: mandatory for wildcard certificate generation.
  53. #
  54. # Optional
  55. #
  56. --certificatesResolvers.sample.acme.dnsChallenge=true
  58. # DNS provider used.
  59. #
  60. # Required
  61. #
  62. --certificatesResolvers.sample.acme.dnsChallenge.provider=digitalocean
  64. # By default, the provider will verify the TXT DNS challenge record before letting ACME verify.
  65. # If delayBeforeCheck is greater than zero, this check is delayed for the configured duration in seconds.
  66. # Useful if internal networks block external DNS queries.
  67. #
  68. # Optional
  69. # Default: 0
  70. #
  71. --certificatesResolvers.sample.acme.dnsChallenge.delayBeforeCheck=0
  73. # Use following DNS servers to resolve the FQDN authority.
  74. #
  75. # Optional
  76. # Default: empty
  77. #
  78. --certificatesResolvers.sample.acme.dnsChallenge.resolvers="1.1.1.1:53,8.8.8.8:53"
  80. # Disable the DNS propagation checks before notifying ACME that the DNS challenge is ready.
  81. #
  82. # NOT RECOMMENDED:
  83. # Increase the risk of reaching Let's Encrypt's rate limits.
  84. #
  85. # Optional
  86. # Default: false
  87. #
  88. --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

  1. [certificatesResolvers.sample.acme]
  2.   # ...
  3.   [certificatesResolvers.sample.acme.tlsChallenge]
  1. certificatesResolvers:
  2.   sample:
  3.     acme:
  4.       # ...
  5.       tlsChallenge: {}
  1. # ...
  2. --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

  1. [entryPoints]
  2.   [entryPoints.web]
  3.     address = ":80"
  5.   [entryPoints.web-secure]
  6.     address = ":443"
  8. [certificatesResolvers.sample.acme]
  9.   # ...
  10.   [certificatesResolvers.sample.acme.httpChallenge]
  11.     entryPoint = "web"
  1. entryPoints:
  2.   web:
  3.     address: ":80"
  5.   web-secure:
  6.     address: ":443"
  8. certificatesResolvers:
  9.   sample:
  10.     acme:
  11.       # ...
  12.       httpChallenge:
  13.         entryPoint: web
  1. --entryPoints.web.address=":80"
  2. --entryPoints.websecure.address=":443"
  3. # ...
  4. --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

  1. [certificatesResolvers.sample.acme]
  2.   # ...
  3.   [certificatesResolvers.sample.acme.dnsChallenge]
  4.     provider = "digitalocean"
  5.     delayBeforeCheck = 0
  6. # ...
  1. certificatesResolvers:
  2.   sample:
  3.     acme:
  4.       # ...
  5.       dnsChallenge:
  6.         provider: digitalocean
  7.         delayBeforeCheck: 0
  8.     # ...
  1. # ...
  2. --certificatesResolvers.sample.acme.dnsChallenge.provider=digitalocean
  3. --certificatesResolvers.sample.acme.dnsChallenge.delayBeforeCheck=0
  4. # ...

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 NameProvider CodeEnvironment Variables
ACME DNSacme-dnsACME_DNS_API_BASE, ACME_DNS_STORAGE_PATHAdditional configuration
Alibaba CloudalidnsALICLOUD_ACCESS_KEY, ALICLOUD_SECRET_KEY, ALICLOUD_REGION_IDAdditional configuration
AuroradnsauroradnsAURORA_USER_ID, AURORA_KEY, AURORA_ENDPOINTAdditional configuration
AzureazureAZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_SUBSCRIPTION_ID, AZURE_TENANT_ID, AZURE_RESOURCE_GROUP, [AZURE_METADATA_ENDPOINT]Additional configuration
BindmanbindmanBINDMAN_MANAGER_ADDRESSAdditional configuration
Blue CatbluecatBLUECAT_SERVER_URL, BLUECAT_USER_NAME, BLUECAT_PASSWORD, BLUECAT_CONFIG_NAME, BLUECAT_DNS_VIEWAdditional configuration
ClouDNScloudnsCLOUDNS_AUTH_ID, CLOUDNS_AUTH_PASSWORDAdditional configuration
CloudflarecloudflareCF_API_EMAIL, CF_API_KEY - The Global API Key needs to be used, not the Origin CA KeyAdditional configuration
CloudXNScloudxnsCLOUDXNS_API_KEY, CLOUDXNS_SECRET_KEYAdditional configuration
ConoHaconohaCONOHA_TENANT_ID, CONOHA_API_USERNAME, CONOHA_API_PASSWORDAdditional configuration
DigitalOceandigitaloceanDO_AUTH_TOKENAdditional configuration
DNSimplednsimpleDNSIMPLE_OAUTH_TOKEN, DNSIMPLE_BASE_URLAdditional configuration
DNS Made EasydnsmadeeasyDNSMADEEASY_API_KEY, DNSMADEEASY_API_SECRET, DNSMADEEASY_SANDBOXAdditional configuration
DNSPoddnspodDNSPOD_API_KEYAdditional configuration
Domain Offensive (do.de)dodeDODE_TOKENAdditional configuration
DreamHostdreamhostDREAMHOST_API_KEYAdditional configuration
Duck DNSduckdnsDUCKDNS_TOKENAdditional configuration
DyndynDYN_CUSTOMER_NAME, DYN_USER_NAME, DYN_PASSWORDAdditional configuration
EasyDNSeasydnsEASYDNS_TOKEN, EASYDNS_KEYAdditional configuration
External ProgramexecEXEC_PATHAdditional configuration
ExoscaleexoscaleEXOSCALE_API_KEY, EXOSCALE_API_SECRET, EXOSCALE_ENDPOINTAdditional configuration
Fast DNSfastdnsAKAMAI_CLIENT_TOKEN, AKAMAI_CLIENT_SECRET, AKAMAI_ACCESS_TOKENAdditional configuration
GandigandiGANDI_API_KEYAdditional configuration
Gandi v5gandiv5GANDIV5_API_KEYAdditional configuration
GlesysglesysGLESYS_API_USER, GLESYS_API_KEY, GLESYS_DOMAINAdditional configuration
GoDaddygodaddyGODADDY_API_KEY, GODADDY_API_SECRETAdditional configuration
Google Cloud DNSgcloudGCE_PROJECT, Application Default Credentials 23, [GCE_SERVICE_ACCOUNT_FILE]Additional configuration
hosting.dehostingdeHOSTINGDE_API_KEY, HOSTINGDE_ZONE_NAMEAdditional configuration
HTTP requesthttpreqHTTPREQ_ENDPOINT, HTTPREQ_MODE, HTTPREQ_USERNAME, HTTPREQ_PASSWORD 1Additional configuration
IIJiijIIJ_API_ACCESS_KEY, IIJ_API_SECRET_KEY, IIJ_DO_SERVICE_CODEAdditional configuration
INWXinwxINWX_USERNAME, INWX_PASSWORDAdditional configuration
Joker.comjokerJOKER_API_KEY or JOKER_USERNAME, JOKER_PASSWORDAdditional configuration
LightsaillightsailAWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, DNS_ZONEAdditional configuration
LinodelinodeLINODE_API_KEYAdditional configuration
Linode v4linodev4LINODE_TOKENAdditional configuration
manual-none, but you need to run Traefik interactively 4, turn on debug log to see instructions and press Enter.
MyDNS.jpmydnsjpMYDNSJP_MASTER_ID, MYDNSJP_PASSWORDAdditional configuration
NamecheapnamecheapNAMECHEAP_API_USER, NAMECHEAP_API_KEYAdditional configuration
name.comnamedotcomNAMECOM_USERNAME, NAMECOM_API_TOKEN, NAMECOM_SERVERAdditional configuration
NamesilonamesiloNAMESILO_API_KEYAdditional configuration
NetcupnetcupNETCUP_CUSTOMER_NUMBER, NETCUP_API_KEY, NETCUP_API_PASSWORDAdditional configuration
NIFCloudnifcloudNIFCLOUD_ACCESS_KEY_ID, NIFCLOUD_SECRET_ACCESS_KEYAdditional configuration
Ns1ns1NS1_API_KEYAdditional configuration
Open Telekom CloudotcOTC_DOMAIN_NAME, OTC_USER_NAME, OTC_PASSWORD, OTC_PROJECT_NAME, OTC_IDENTITY_ENDPOINTAdditional configuration
OVHovhOVH_ENDPOINT, OVH_APPLICATION_KEY, OVH_APPLICATION_SECRET, OVH_CONSUMER_KEYAdditional configuration
Openstack DesignatedesignateOS_AUTH_URL, OS_USERNAME, OS_PASSWORD, OS_TENANT_NAME, OS_REGION_NAMEAdditional configuration
Oracle CloudoraclecloudOCI_COMPARTMENT_OCID, OCI_PRIVKEY_FILE, OCI_PRIVKEY_PASS, OCI_PUBKEY_FINGERPRINT, OCI_REGION, OCI_TENANCY_OCID, OCI_USER_OCIDAdditional configuration
PowerDNSpdnsPDNS_API_KEY, PDNS_API_URLAdditional configuration
RackspacerackspaceRACKSPACE_USER, RACKSPACE_API_KEYAdditional configuration
RFC2136rfc2136RFC2136_TSIG_KEY, RFC2136_TSIG_SECRET, RFC2136_TSIG_ALGORITHM, RFC2136_NAMESERVERAdditional configuration
Route 53route53AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, [AWS_REGION], [AWS_HOSTED_ZONE_ID] or a configured user/instance IAM profile.Additional configuration
Sakura CloudsakuracloudSAKURACLOUD_ACCESS_TOKEN, SAKURACLOUD_ACCESS_TOKEN_SECRETAdditional configuration
SelectelselectelSELECTEL_API_TOKENAdditional configuration
StackpathstackpathSTACKPATH_CLIENT_ID, STACKPATH_CLIENT_SECRET, STACKPATH_STACK_IDAdditional configuration
TransIPtransipTRANSIP_ACCOUNT_NAME, TRANSIP_PRIVATE_KEY_PATHAdditional configuration
VegaDNSvegadnsSECRET_VEGADNS_KEY, SECRET_VEGADNS_SECRET, VEGADNS_URLAdditional configuration
VersioversioVERSIO_USERNAME, VERSIO_PASSWORDAdditional configuration
VscalevscaleVSCALE_API_TOKENAdditional configuration
VULTRvultrVULTR_API_KEYAdditional configuration
Zone.eezoneeeZONEEE_API_USER, ZONEEE_API_KEYAdditional 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.

  1. [certificatesResolvers.sample.acme]
  2.   # ...
  3.   [certificatesResolvers.sample.acme.dnsChallenge]
  4.     # ...
  5.     resolvers = ["1.1.1.1:53", "8.8.8.8:53"]
  1. certificatesResolvers:
  2.   sample:
  3.     acme:
  4.       # ...
  5.       dnsChallenge:
  6.         # ...
  7.         resolvers:
  8.         - "1.1.1.1:53"
  9.         - "8.8.8.8:53"
  1. # ...
  2. --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

  1. [certificatesResolvers.sample.acme]
  2.   # ...
  3.   caServer = "https://acme-staging-v02.api.letsencrypt.org/directory"
  4.   # ...
  1. certificatesResolvers:
  2.   sample:
  3.     acme:
  4.       # ...
  5.       caServer: https://acme-staging-v02.api.letsencrypt.org/directory
  6.       # ...
  1. # ...
  2. --certificatesResolvers.sample.acme.caServer="https://acme-staging-v02.api.letsencrypt.org/directory"
  3. # ...

storage

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

  1. [certificatesResolvers.sample.acme]
  2.   # ...
  3.   storage = "acme.json"
  4.   # ...
  1. certificatesResolvers:
  2.   sample:
  3.     acme:
  4.       # ...
  5.       storage: acme.json
  6.       # ...
  1. # ...
  2. --certificatesResolvers.sample.acme.storage=acme.json
  3. # ...

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:

  1. docker run -v "/my/host/acme.json:acme.json" traefik
  1. 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.