Examples

You will find here some configuration examples of Traefik.

HTTP only

  1. defaultEntryPoints = ["http"]
  3. [entryPoints]
  4.   [entryPoints.http]
  5.   address = ":80"

HTTP + HTTPS (with SNI)

  1. defaultEntryPoints = ["http", "https"]
  3. [entryPoints]
  4.   [entryPoints.http]
  5.   address = ":80"
  6.   [entryPoints.https]
  7.   address = ":443"
  8.     [entryPoints.https.tls]
  9.       [[entryPoints.https.tls.certificates]]
  10.       certFile = "integration/fixtures/https/snitest.com.cert"
  11.       keyFile = "integration/fixtures/https/snitest.com.key"
  12.       [[entryPoints.https.tls.certificates]]
  13.       certFile = "integration/fixtures/https/snitest.org.cert"
  14.       keyFile = "integration/fixtures/https/snitest.org.key"

Note that we can either give path to certificate file or directly the file content itself (like in this TOML example).

HTTP redirect on HTTPS

  1. defaultEntryPoints = ["http", "https"]
  3. [entryPoints]
  4.   [entryPoints.http]
  5.   address = ":80"
  6.     [entryPoints.http.redirect]
  7.     entryPoint = "https"
  8.   [entryPoints.https]
  9.   address = ":443"
  10.     [entryPoints.https.tls]
  11.       [[entryPoints.https.tls.certificates]]
  12.       certFile = "examples/traefik.crt"
  13.       keyFile = "examples/traefik.key"

Note

Please note that regex and replacement do not have to be set in the redirect structure if an entrypoint is defined for the redirection (they will not be used in this case)

Let's Encrypt support

Basic example with HTTP challenge

  1. [entryPoints]
  2.   [entryPoints.http]
  3.   address = ":80"
  4.   [entryPoints.https]
  5.   address = ":443"
  6.     [entryPoints.https.tls]
  8. [acme]
  9. email = "[email protected]"
  10. storage = "acme.json"
  11. caServer = "https://acme-staging-v02.api.letsencrypt.org/directory"
  12. entryPoint = "https"
  13.   [acme.httpChallenge]
  14.   entryPoint = "http"
  16. [[acme.domains]]
  17.   main = "local1.com"
  18.   sans = ["test1.local1.com", "test2.local1.com"]
  19. [[acme.domains]]
  20.   main = "local2.com"
  21.   sans = ["test1.local2.com", "test2x.local2.com"]
  22. [[acme.domains]]
  23.   main = "local3.com"
  24. [[acme.domains]]
  25.   main = "local4.com"

This configuration allows generating Let's Encrypt certificates (thanks to HTTP-01 challenge) for the four domains local[1-4].com with described SANs.

Traefik generates these certificates when it starts and it needs to be restart if new domains are added.

onHostRule option (with HTTP challenge)

  1. [entryPoints]
  2.   [entryPoints.http]
  3.   address = ":80"
  4.   [entryPoints.https]
  5.   address = ":443"
  6.     [entryPoints.https.tls]
  8. [acme]
  9. email = "[email protected]"
  10. storage = "acme.json"
  11. onHostRule = true
  12. caServer = "https://acme-staging-v02.api.letsencrypt.org/directory"
  13. entryPoint = "https"
  14.   [acme.httpChallenge]
  15.   entryPoint = "http"
  17. [[acme.domains]]
  18.   main = "local1.com"
  19.   sans = ["test1.local1.com", "test2.local1.com"]
  20. [[acme.domains]]
  21.   main = "local2.com"
  22.   sans = ["test1.local2.com", "test2x.local2.com"]
  23. [[acme.domains]]
  24.   main = "local3.com"
  25. [[acme.domains]]
  26.   main = "local4.com"

This configuration allows generating Let's Encrypt certificates (thanks to HTTP-01 challenge) for the four domains local[1-4].com.

Traefik generates these certificates when it starts.

If a backend is added with a onHost rule, Traefik will automatically generate the Let's Encrypt certificate for the new domain (for frontends wired on the acme.entryPoint).

OnDemand option (with HTTP challenge)

  1. [entryPoints]
  2.   [entryPoints.http]
  3.   address = ":80"
  4.   [entryPoints.https]
  5.   address = ":443"
  6.     [entryPoints.https.tls]
  8. [acme]
  9. email = "[email protected]"
  10. storage = "acme.json"
  11. onDemand = true
  12. caServer = "https://acme-staging-v02.api.letsencrypt.org/directory"
  13. entryPoint = "https"
  14.   [acme.httpChallenge]
  15.   entryPoint = "http"

This configuration allows generating a Let's Encrypt certificate (thanks to HTTP-01 challenge) during the first HTTPS request on a new domain.

Note

This option simplifies the configuration but :

That's why, it's better to use the onHostRule option if possible.

DNS challenge

  1. [entryPoints]
  2.   [entryPoints.https]
  3.   address = ":443"
  4.     [entryPoints.https.tls]
  6. [acme]
  7. email = "[email protected]"
  8. storage = "acme.json"
  9. caServer = "https://acme-staging-v02.api.letsencrypt.org/directory"
  10. entryPoint = "https"
  11.   [acme.dnsChallenge]
  12.   provider = "digitalocean" # DNS Provider name (cloudflare, OVH, gandi...)
  13.   delayBeforeCheck = 0
  15. [[acme.domains]]
  16.   main = "local1.com"
  17.   sans = ["test1.local1.com", "test2.local1.com"]
  18. [[acme.domains]]
  19.   main = "local2.com"
  20.   sans = ["test1.local2.com", "test2x.local2.com"]
  21. [[acme.domains]]
  22.   main = "local3.com"
  23. [[acme.domains]]
  24.   main = "local4.com"

DNS challenge needs environment variables to be executed. These variables have to be set on the machine/container that host Traefik.

These variables are described in this section.

DNS challenge with wildcard domains

  1. [entryPoints]
  2.   [entryPoints.https]
  3.   address = ":443"
  4.     [entryPoints.https.tls]
  6. [acme]
  7. email = "[email protected]"
  8. storage = "acme.json"
  9. caServer = "https://acme-staging-v02.api.letsencrypt.org/directory"
  10. entryPoint = "https"
  11.   [acme.dnsChallenge]
  12.   provider = "digitalocean" # DNS Provider name (cloudflare, OVH, gandi...)
  13.   delayBeforeCheck = 0
  15. [[acme.domains]]
  16.   main = "*.local1.com"
  17. [[acme.domains]]
  18.   main = "local2.com"
  19.   sans = ["test1.local2.com", "test2x.local2.com"]
  20. [[acme.domains]]
  21.   main = "*.local3.com"
  22. [[acme.domains]]
  23.   main = "*.local4.com"

DNS challenge needs environment variables to be executed. These variables have to be set on the machine/container that host Traefik.

These variables are described in this section.

More information about wildcard certificates are available in this section.

onHostRule option and provided certificates (with HTTP challenge)

  1. [entryPoints]
  2.   [entryPoints.http]
  3.   address = ":80"
  4.   [entryPoints.https]
  5.   address = ":443"
  6.     [entryPoints.https.tls]
  7.       [[entryPoints.https.tls.certificates]]
  8.       certFile = "examples/traefik.crt"
  9.       keyFile = "examples/traefik.key"
  11. [acme]
  12. email = "[email protected]"
  13. storage = "acme.json"
  14. onHostRule = true
  15. caServer = "http://172.18.0.1:4000/directory"
  16. entryPoint = "https"
  17.   [acme.httpChallenge]
  18.   entryPoint = "http"

Traefik will only try to generate a Let's encrypt certificate (thanks to HTTP-01 challenge) if the domain cannot be checked by the provided certificates.

Cluster mode

Prerequisites

Before you use Let's Encrypt in a Traefik cluster, take a look to the key-value store explanations and more precisely at this section, which will describe how to migrate from a acme local storage (acme.json file) to a key-value store configuration.

Configuration

  1. [entryPoints]
  2.   [entryPoints.http]
  3.   address = ":80"
  4.   [entryPoints.https]
  5.   address = ":443"
  6.     [entryPoints.https.tls]
  8. [acme]
  9. email = "[email protected]"
  10. storage = "traefik/acme/account"
  11. caServer = "http://172.18.0.1:4000/directory"
  12. entryPoint = "https"
  14. [acme.httpChallenge]
  15.     entryPoint = "http"
  17. [[acme.domains]]
  18.   main = "local1.com"
  19.   sans = ["test1.local1.com", "test2.local1.com"]
  20. [[acme.domains]]
  21.   main = "local2.com"
  22.   sans = ["test1.local2.com", "test2x.local2.com"]
  23. [[acme.domains]]
  24.   main = "local3.com"
  25. [[acme.domains]]
  26.   main = "local4.com"
  28. [consul]
  29.   endpoint = "127.0.0.1:8500"
  30.   watch = true
  31.   prefix = "traefik"

This configuration allows to use the key traefik/acme/account to get/set Let's Encrypt certificates content. The consul provider contains the configuration.

Note

It's possible to use others key-value store providers as described here.

Override entrypoints in frontends

  1. [frontends]
  3.   [frontends.frontend1]
  4.   backend = "backend2"
  5.     [frontends.frontend1.routes.test_1]
  6.     rule = "Host:test.localhost"
  8.   [frontends.frontend2]
  9.   backend = "backend1"
  10.   passHostHeader = true
  11.   entrypoints = ["https"] # overrides defaultEntryPoints
  12.     [frontends.frontend2.routes.test_1]
  13.     rule = "Host:{subdomain:[a-z]+}.localhost"
  15.   [frontends.frontend3]
  16.   entrypoints = ["http", "https"] # overrides defaultEntryPoints
  17.   backend = "backend2"
  18.   rule = "Path:/test"

Override the Traefik HTTP server idleTimeout and/or throttle configurations from re-loading too quickly

  1. providersThrottleDuration = "5s"
  3. [respondingTimeouts]
  4. idleTimeout = "360s"

Using labels in docker-compose.yml

Pay attention to the labels section:

  1. home:
  2.   image: abiosoft/caddy:0.10.14
  3.   networks:
  4.     - ntw_front
  5.   volumes:
  6.     - ./www/home/srv/:/srv/
  7.   deploy:
  8.     mode: replicated
  9.     replicas: 2
  10.     #placement:
  11.     #  constraints: [node.role==manager]
  12.     restart_policy:
  13.       condition: on-failure
  14.       max_attempts: 5
  15.     resources:
  16.       limits:
  17.         cpus: '0.20'
  18.         memory: 9M
  19.       reservations:
  20.         cpus: '0.05'
  21.         memory: 9M
  22.     labels:
  23.       - "traefik.frontend.rule=PathPrefixStrip:/"
  24.       - "traefik.backend=home"
  25.       - "traefik.port=2015"
  26.       - "traefik.weight=10"
  27.       - "traefik.enable=true"
  28.       - "traefik.passHostHeader=true"
  29.       - "traefik.docker.network=ntw_front"
  30.       - "traefik.frontend.entryPoints=http"
  31.       - "traefik.backend.loadbalancer.swarm=true"
  32.       - "traefik.backend.loadbalancer.method=drr"

Something more tricky using regex.

In this case a slash is added to siteexample.io/portainer and redirect to siteexample.io/portainer/. For more details: https://github.com/containous/traefik/issues/563

The double sign $$ are variables managed by the docker compose file (documentation). 

  1. portainer:
  2.   image: portainer/portainer:1.16.5
  3.   networks:
  4.     - ntw_front
  5.   volumes:
  6.     - /var/run/docker.sock:/var/run/docker.sock
  7.   deploy:
  8.     mode: replicated
  9.     replicas: 1
  10.     placement:
  11.       constraints: [node.role==manager]
  12.     restart_policy:
  13.       condition: on-failure
  14.       max_attempts: 5
  15.     resources:
  16.       limits:
  17.         cpus: '0.33'
  18.         memory: 20M
  19.       reservations:
  20.         cpus: '0.05'
  21.         memory: 10M
  22.     labels:
  23.       - "traefik.frontend.rule=PathPrefixStrip:/portainer"
  24.       - "traefik.backend=portainer"
  25.       - "traefik.port=9000"
  26.       - "traefik.weight=10"
  27.       - "traefik.enable=true"
  28.       - "traefik.passHostHeader=true"
  29.       - "traefik.docker.network=ntw_front"
  30.       - "traefik.frontend.entryPoints=http"
  31.       - "traefik.backend.loadbalancer.swarm=true"
  32.       - "traefik.backend.loadbalancer.method=drr"
  33.       # https://github.com/containous/traefik/issues/563#issuecomment-421360934
  34.       - "traefik.frontend.redirect.regex=^(.*)/portainer$$"
  35.       - "traefik.frontend.redirect.replacement=$$1/portainer/"
  36.       - "traefik.frontend.rule=PathPrefix:/portainer;ReplacePathRegex: ^/portainer/(.*) /$$1"