HomeDiscordYouTubeDisclaimer

Config Files Explained

To get set up, we need to write a few config files to tell Traefik what to do and how. Traefik is very versatile and so there are many ways to set it up. Thanks to our community member beaussan, we believe we have managed to simplify the process as much as possible and have also broken down all the information to make each step understandable.

traefik.yml

At start up, Traefik looks for a file names Traefik.yml. This is the first and key config file that will be mainly setting up Traefik, telling it where any other files might be and also what domains to use and how to get certificates for them. This is a static file, which means that any changes to this file require a restart of Traefik to load in those changes.

Find more information here.

Global Parameters

In the config file snippet below, we are setting a few global parameters. We are telling Traefik to check for new versions and then within the logs, it will tell us that a newer version is available. We are also opting out of sending anonymous usage information to the developers of Traefik. If you would like to support the project, then we suggest that you enable this by changing the default value from false to true.

global:
  checkNewVersion: true
  sendAnonymousUsage: false

The setting below is to allow insecure backend connections. Usually, these backend connections are either via the internal docker network or over a secure LAN. This setting allows for Traefik to connect to a that use HTTPS by default but maybe do not have a valid certificate. Allowing for this insecure backend connection allows Traefik to connect to the app and give it a secure frontend connection.

serversTransport:
  insecureSkipVerify: true

EntryPoints

EntryPoints are the network entry points into Traefik. They define the port which will receive the packets, and whether to listen for TCP or UDP. This configuration is basically telling Traefik where and how to accept incoming connections. For the HTTP incoming request, we are telling Traefik to accept them on the default port 80. You can also see that we have added a redirection rule to forward it by default to the HTTPS EntryPoint.

Added to this section is all of Cloudflare's IP ranges as trusted IP's. Using the forwardHeaders: and trustedIPs: arguments, this will allow HTTP requests to forward their real IP's through Traefik.

Next we are telling Traefik to accept HTTPS requests on the default port 443. For HTTPS requests, we are going to need valid certificates. In this configuration here we are telling Traefik to use lets encrypt to make the certificates and we are also telling Traefik to create those certificates for not only just the root domain but also all of the subdomains too with a wildcard variable.

For all HTTPS requests, we are able to set a few middlewares to use by default. In our example we will just be using the one for secure headers (securityHeaders@file) which will be explained further in the guide. If you would like any other middlewares to be loaded by default for all requests, this is where you will add them. As an example, you could add the Authelia middleware (auth@file) to this location, and then every request will be sent to Authelia first.

entryPoints:
  # Not used in apps, but redirect everything from HTTP to HTTPS
  http:
    address: :80
    forwardedHeaders:
      trustedIPs: &trustedIps
        # Start of Clouflare public IP list for HTTP requests, remove this if you don't use it
        - 173.245.48.0/20
        - 103.21.244.0/22
        - 103.22.200.0/22
        - 103.31.4.0/22
        - 141.101.64.0/18
        - 108.162.192.0/18
        - 190.93.240.0/20
        - 188.114.96.0/20
        - 197.234.240.0/22
        - 198.41.128.0/17
        - 162.158.0.0/15
        - 104.16.0.0/12
        - 172.64.0.0/13
        - 131.0.72.0/22
        - 2400:cb00::/32
        - 2606:4700::/32
        - 2803:f800::/32
        - 2405:b500::/32
        - 2405:8100::/32
        - 2a06:98c0::/29
        - 2c0f:f248::/32
        # End of Cloudlare public IP list
    http:
      redirections:
        entryPoint:
          to: https
          scheme: https

  # HTTPS endpoint, with domain wildcard
  https:
    address: :443
    forwardedHeaders:
      # Reuse list of Cloudflare Trusted IP's above for HTTPS requests
      trustedIPs: *trustedIps
    http:
      tls:
        # Generate a wildcard domain certificate
        certResolver: letsencrypt
        domains:
          - main: YOURDOMAIN.COM
            sans:
              - '*.YOURDOMAIN.COM'
      middlewares:
        - securityHeaders@file

Providers

Providers discover the services that live on your infrastructure. The idea is that Traefik queries the provider APIs in order to find relevant information about routing, and when Traefik detects a change, it dynamically updates the routes.

The file provider lets you define the dynamic configuration in a YAML or TOML file. Here we are using a YAML file to tell Traefik to look at another file for more settings. Both of these config files could be added to the default Traefik.yml but to split the information out and also allow for dynamic changes, it is good to have another file and to set Traefik up to watch this file for changes.

The next setting is one of the clever features of Traefik and allows us to dynamically and automatically add new apps to Traefik by only adding a few labels to the app. The docker settings below tell Traefik to watch the docker network for new apps. Once it detects a new app, it will look for certain labels (which we will cover later in the guide) and will then use those labels to dynamically create routes to the app. We are telling Traefik which network to monitor (in our example it's proxy) and to also check it every 15 seconds for changes. For new docker containers we have given it a clever rule to take the app name, and add it as a subdomain and to proxy the app with that. Make sure to add your root domain to this rule for it to work correctly.

providers:
  providersThrottleDuration: 2s

  # File provider for connecting things that are outside of docker / defining middleware
  file:
    filename: /etc/traefik/fileConfig.yml
    watch: true

  # Docker provider for connecting all apps that are inside of the docker network
  docker:
    watch: true
    network: proxy # Add Your Docker Network Name Here
    # Default host rule to containername.domain.example
    defaultRule: "Host(`{{ index .Labels \"com.docker.compose.service\"}}.YOURDOMAIN.COM`)"
    swarmModeRefreshSeconds: 15s #comment out or remove this line if using traefik v3
    exposedByDefault: false

Please Note

If you have decided to go with the more secure mothod for allowing Traefik access to the docker socket (API) then you will have to add an extra line to the bootom of this section.

    endpoint: "tcp://dockersocket:2375"

Please Note: Traefik v3 Modifications Changes have been made as part of Traefik v3 which may break your config. The following line in the docker section will need to be removed or commented out if you are using or upgrading to traefik v3

// Some code
swarmModeRefreshSeconds

Please refer to the Migration guide for additional changes https://doc.traefik.io/traefik/master/migration/v2-to-v3/

Traefik Dashboard

Traefik exposes a good deal of information through an API handler, such as the configuration of all routers, services, middlewares, etc. The dashboard is the central place that shows you the current active routes handled by Traefik. Below we are simply enabling the Traefik dashboard but leaving it insecure as we are going to secure it with let's encrypt certs and Authelia. If you do not think you will use these features, then simply set the dashboard: to false.

# Enable traefik ui
api:
  dashboard: true
  insecure: true

Logs

Traefik logs concern everything that happens to Traefik itself (startup, configuration, events, shutdown, and so on). Here we are setting the log level for Traefik. If you are having issues getting it set up or proxying an app, then it is a good idea to set this to DEBUG and restart the app. You will now see much more detail in the logs. By default, the logs are written to the standard output. You can configure a file path instead using the filePath option.

# Log level INFO|DEBUG|ERROR
log:
  level: INFO

Certificate Resolver

Traefik requires you to define "Certificate Resolvers" in the static configuration, which are responsible for retrieving certificates from an ACME server. 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.

This is where we are going to set up the cert creation. Below, we are telling Traefik here to use let's encrypt to generate certificates for our domain. To make sure that let's encrypt is able to generate certificates, we need to give it some information. You will need to add your email so that you can be notified if your cert is ever going to run out. Traefik by default renews these certificates for you, but if there is ever an issue then you will be emailed notifying you.

We are telling Traefik that we want to use Cloudflare to make the DNS challenge request and also to use Cloudflare as the DNS resolver for these requests. Earlier in the guide when setting up the template for Traefik we already added the Cloudflare API token and email as a global environment variable and so Traefik will be able to pick those credentials up when making these requests.

# Use letsencrypt to generate ssl serficiates
certificatesResolvers:
  letsencrypt:
    acme:
      email: YOUR@EMAIL.COM  # change to your provider account email address.
      storage: /etc/traefik/acme.json
      dnsChallenge:
        provider: cloudflare
        # Used to make sure the dns challenge is propagated to the rights dns servers
        resolvers:
          - "1.1.1.1:53"
          - "1.0.0.1:53"

fileConfig.yml

This is a dynamic file, meaning that if we make any changes to the file, Traefik will pick them up and load them in automatically. We will use this file to manage all the middlewares and also add any external services like VM's. In the example below, we will be adding Homeassistant.

Routers & Services

A router is in charge of connecting incoming requests to the services that can handle them. In the process, routers may use pieces of middleware to update the request, or act before forwarding the request to the service.

The Services are responsible for configuring how to reach the actual services that will eventually handle the incoming requests.

To add an external application we need to give Traefik a router which tells Traefik how to route the requests and which middleware to use along the way and then a matching service which tells Traefik where to point the requests.

http:
    ## EXTERNAL ROUTING ##
  routers:
    # Homeassistant routing
    homeassistant:
      entryPoints:
        - https
      rule: 'Host(`homeassistant.YOURDOMAIN.COM`)'
      service: homeassistant
      middlewares:
        - "auth"  
  ## SERVICES ##
  services:
    # Homeassistant service
    homeassistant:
      loadBalancer:
        servers:
          - url: http://192.168.60.5:8123/

Middleware

Now we are going to be adding middlewares that you can manually add to each service.

Attached to the routers, pieces of middleware are a means of tweaking the requests before they are sent to your service (or before the answer from the services are sent to the clients).

There are several available middleware in Traefik, some can modify the request, the headers, some are in charge of redirections, some add authentication, and so on.

Middlewares that use the same protocol can be combined into chains to fit every scenario. We are going to use these to do many things including adjusting headers to secure the app or even forward requests to Authelia.

IpWhitelist

The IpWhitelist middleware accepts / refuses requests based on the client IP. This can be handy when you have a public domain and only want some apps being accessed by certain networks.

Example: you have your public site on domain.tld and have your testing site on test.domain.tld. the public one can be visited by anyone but the test can only be visited when you are in a predefined network.

local-ipwhitelist
  ## MIDDLEWARES ##
  middlewares:
    # Only Allow Local networks
    local-ipwhitelist:
      ipWhiteList:
        sourceRange: 
          - 127.0.0.1/32 # localhost
          - 192.168.1.1/24 # LAN Subnet

In the example above you will see 2 ranges, the 127.0.0.1/32 range is used by the machine that's running Traefik and needs to stay. The 192.168.1.1/24 range is a local network, one make sure to check your desired network ranges and add them accordingly. You can also add a single IP to the list, not only ranges

To add this to a container add fillowing label: `traefik.http.routers.APPNAME.middlewares: local-ipwhitelist@file`

Forward Auth

The ForwardAuth middleware delegates authentication to an external service. If the service answers with a 2XX code, access is granted, and the original request is performed. Otherwise, the response from the authentication server is returned.

We will be using the "auth" middleware to forward requests to Authelia to make sure that the user visiting the service is verified and is authorised to visit the app. In this middleware, we will also be adding a few headers to forward on authorisation information to the app that we are visiting. Some apps allow you to forward on auth requests and allow you to login without having to add your details twice (too Authelia and then also the app).

You will have to replace AUTHELIA_CONTAINER_NAME with your Authelia container name and AUTHELIA_SUBDOMAIN with the subdomain you chose for your Authelia portal.

This middleware is able to be added to an application by simply adding a label to the docker container you are wanting to protect, explained a bit further in the guide (Enabling Authelia).

auth:
  ## MIDDLEWARES ##
  middlewares:
  # Authelia guard
    auth:
      forwardauth:
        address: http://AUTHELIA_CONTAINER_NAME:9091/api/verify?rd=https://AUTHELIA_SUBDOMAIN.YOURDOMAIN.COM/
        trustForwardHeader: true
        authResponseHeaders:
          - Remote-User
          - Remote-Groups
          - Remote-Name
          - Remote-Email
auth-basic:
    # Authelia basic auth guard
    auth-basic:
      forwardauth:
        address: http://auth:9091/api/verify?auth=basic
        trustForwardHeader: true
        authResponseHeaders:
          - Remote-User
          - Remote-Groups
          - Remote-Name
          - Remote-Email

Headers

The Headers middleware manages the headers of requests and responses. Below is the "securityHeaders" middleware. We will be using this to add secure headers to all requests. Using the below headers we are able to take our SSL score up to an A+ without compromising functionality of our apps. This will help towards keeping your apps secure.

As explained in the Entrypoint section of the traefik.yml explanation, we added this middleware to be used by default for all requests passed through Traefik.

securityHeaders:
    # Security headers
    securityHeaders:
      headers:
        customResponseHeaders:
          X-Robots-Tag: "none,noarchive,nosnippet,notranslate,noimageindex"
          server: ""
        sslProxyHeaders:
          X-Forwarded-Proto: https
        referrerPolicy: "same-origin"
        hostsProxyHeaders:
          - "X-Forwarded-Host"
        customRequestHeaders:
          X-Forwarded-Proto: "https"
        customResponseHeaders:
          X-Forwarded-Proto: "https"
        contentTypeNosniff: true
        browserXssFilter: true
        forceSTSHeader: true
        stsIncludeSubdomains: true
        stsSeconds: 63072000
        stsPreload: true

PLEASE NOTE

If you are using cloudflare as your DNS provider, it is possible for them to overide the headers set in this middleware. If you are having issues and need to have a specific set of security headers, it may be worth double checking your cloudflare settings to make sure they all match up (Nextcloud STSSeconds for example).

You can double check the headers that are being used for your domain with this tool, suggested by our community member @88pockets

https://securityheaders.com/

Proxying Your First App

PreviousDocker ComposeNexttraefik.yml Example

Last updated