• Let's Encrypt
    • Configuration Examples
    • Automatic Renewals
    • The Different ACME Challenges
      • tlsChallenge
      • httpChallenge
      • dnsChallenge
        • providers
        • resolvers
        • Wildcard Domains
    • caServer
    • storage
      • In a File
    • Fallback

    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.

    • 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. ↩