Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
For those of you running Linux servers or if you use docker-compose then you can install Traefik using our docker-compose.yml file example.
First, ensure that you have created a custom docker network, we will talk about why this is the preferred method further into the guide (see video here if you are unsure). For this example, we will use the custom docker network called "proxy".
Let's create the folder to add this compose file too, you might save your app's data in another location so just add your path to this command.
Traefik needs a file called acme.json to store the SSL certificate information too and this needs to be secure. So, we will create this file and change the permissions to suit.
Now let's create the docker-compose file with the nano text editor
Paste in the following and edit line 15 to add your domain, line 21 with your Cloudflare credentials. If you have already created your own docker network, then you will have to change lines 13 and 27 and replace proxy with your own network name. In our example, we are going to use /opt/appdata as the default location to store the application's data. If you would like to store your app's data in another location, then you can adjust this on line 11.
To get your API token, visit Cloudflare, go to My Profile, select API tokens and then choose Create Token.
Use the template Edit zone DNS.
Change to the following settings, click Continue to Summary and then Create Token.
Zone - Zone Settings - Read
Zone - Zone - Read
Zone - DNS - Edit
Zone Resources - Include - All Zones
Giving docker API access to a publicly accessible docker container is a security liability, and so it would be preferred to try to limit the amount of access this container has to the API. We can achieve this by using a proxy container that allows limited access to the Docker API and only allow through what we need to make things work.
PLEASE NOTE
If you are going to use this method please pay extra attention to the "provider" section of the traefik.yml configuration file. You will need to add an extra line to the configuration file.
Warning - Insecure Method
Allowing a container direct access to docker.sock is insecure and could make your system vulnerable to attack. Please read the following post to see more about the vulnerabilities of sharing docker.sock with docker containers and how it could compromise your server.
The Danger of Exposing docker.sock
Close and save this file by pressing ctrl + x, type "y" and then press enter.
Now we want to start up the Traefik container.
If you are in the same directory as the compose file, you can run the following.
If you are in another directory, then you will need to specify the compose file with the -f argument.
In order to have a fully running Traefik set-up you are going to need to add two config files, traefik.yml and fileConfig.yml explained on the page linked below.
Now if we were to put everything together into our static Traefik config file, it would look something like the below. Use your favourite method for adding/editing the file and paste it below. In our example, we will use the simple command-line file editor nano. Anywhere you see YOURDOMAIN.COM or YOUR@EMAIL.COM, make sure to change that out for your own information.
nano /opt/appdata/traefik/traefik.yml
Rather than allowing Traefik to use the container name for the app's subdomain, you may want to manually choose the domain/subdomain used. Adding this additional label, you are able to manually override the default docker provider rule.
If you are using docker-compose then you simply need to add a single line to the compose files under labels:
WARNING
You must replace app with the name of your application that this label is being added to otherwise Traefik will see duplicates.
To show you a full example, we will add the label to an existing docker-compose.yml file for Adminer.
Now while in the same directory as the docker-compose.yml file, run the command docker-compose up -d and it should recreate the container for you with the latest labels. Now, when you deploy your application, you will be able to visit it by going to your domain with the app name as the subdomain (APP-NAME.DOMAIN.COM).
PLEASE NOTE
You can add multiple of these labels at once before finally deploying your application.
Traefik will now use your preferred subdomain to forward all traffic on to the app correctly.
Now, if we were to put everything together into our dynamic Traefik config file, it would look something like the below. Use your favourite method for adding/editing the file and paste it below. In our example, we will use the simple command-line file editor nano. Anywhere you see YOURDOMAIN.COM, make sure to change that out for your own domain.
nano /opt/appdata/traefik/fileConfig.yml
By default, Traefik picks up exposed ports for every app using the default dockerfile. If for some reason the developer did not add this port to the dockerfile or multiple ports are exposed, we may have to tell Traefik which port to use for the web UI.
If you are using docker-compose then you simply need to add a single line to the compose files under labels:
WARNING
You must replace app with the name of your application that this label is being added to otherwise Traefik will see duplicates.
To show you a full example, we will add the label to an existing docker-compose.yml file for Adminer.
Now while in the same directory as the docker-compose.yml file, run the command docker-compose up -d and it should recreate the container for you with the latest labels. Now when you deploy your application you will be able to visit it by going to your domain with the app name as the subdomain (APP-NAME.DOMAIN.COM).
PLEASE NOTE
You can add multiple of these labels at once before finally deploying your application.
Traefik will now use the port specified to forward all traffic to the app correctly.
Before we can enable Traefik to forward auth requests to Authelia, we need to first reverse proxy the Authelia app through Traefik. In order to do that, we will add the minimum default two labels to proxy any app.
WARNING
You must replace app with the name of your application that this label is being added to otherwise Traefik will see duplicates.
To show how this would look in your Authelia docker-compose.yml file, below is an example:
To enable Traefik to forward auth requests to Authelia for an application, we just have to simply set a label for Traefik to pick up. This label will tell Traefik to use a certain middleware for the application we are adding it to.
If you are using docker-compose then you simply need to add a single line to the compose files under labels:
WARNING
You must replace app with the name of your application that this label is being added to otherwise Traefik will see duplicates.
To show you a full example, we will add the label to an existing docker-compose.yml file for Adminer.
Now while in the same directory as the docker-compose.yml file, run the command docker-compose up -d and it should recreate the container for you with the latest labels. Now when you deploy your application you will be able to visit it by going to your domain with the app name as the subdomain (APP-NAME.DOMAIN.COM).
PLEASE NOTE
You can add multiple of these labels at once before finally deploying your application.
IMPORTANT
In order to avoid Authelia redirecting into a loop, you must add this rule to your Access Control section in the Authelia configuration.yml:
Where auth.domainis your authelia subdomain and your root domain.
Traefik will now forward all traffic through Authelia to make sure that the user trying to get to your app is correctly authenticated before passing traffic on to the app.
By default, Traefik connects to the application's backend via HTTP. If the application exposes it's WebUI via HTTPS, then we will need to tell Traefik to use this protocol.
If you are using docker-compose then you simply need to add a single line to the compose files under labels:
WARNING
You must replace app with the name of your application that this label is being added to otherwise Traefik will see duplicates.
To show you a full example, we will add the label to an existing docker-compose.yml file for Adminer.
Now while in the same directory as the docker-compose.yml file, run the command docker-compose up -d and it should recreate the container for you with the latest labels. Now when you deploy your application, you will be able to visit it by going to your domain with the app name as the subdomain (APP-NAME.DOMAIN.COM).
PLEASE NOTE
You can add multiple of these labels at once before finally deploying your application.
Traefik will now use the HTTPS protocol specified to forward all traffic on to the app correctly.
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 , 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.
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 .
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.
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.
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.
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 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.
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.
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
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.
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.
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.
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.
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.
Now we are going to be adding middlewares that you can manually add to each service.
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.
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.
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`
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.
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.
PLEASE NOTE
You can double check the headers that are being used for your domain with this tool, suggested by our community member @88pockets
In some cases, you may find that after changing the scheme to HTTPS, you will have to also specify the application's HTTPS port manually. You can do this by following the short guide on "".
The file provider lets you define the 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.
Please refer to the Migration guide for additional changes
Traefik requires you to define "Certificate Resolvers" in the , 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.
A router is in charge of connecting incoming requests to the services that can handle them. In the process, routers may use pieces of to update the request, or act before forwarding the request to the service.
Attached to the routers, pieces of middleware are a means of tweaking the requests before they are sent to your (or before the answer from the services are sent to the clients).
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 ().
As explained in the section of the explanation, we added this middleware to be used by default for all requests passed through Traefik.
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 ( for example).
The minimal requirements to enable Traefik on a certain app and allow it to proxy the web UI, we have to simply set a label for Traefik to pick up. Labels are a mechanism for applying metadata to Docker objects. Traefik is able to pick up this metadata and can use it to configure itself. This label will tell Traefik that we want to reverse proxy the application we are adding it to.
If you are using docker-compose then you simply need to add these lines to the compose files under labels:
The traefik.enable: true simply tells traefik that you want to proxy this app and the traefik.http.routers.app.entryPoints: https only allows the app to be proxied over HTTPS. This will prevent any possible vulnerabilities in the future. For example, if the HTTP redirect breaks, it will not be able to proxy the app over http accidentally.
WARNING
You must replace app with the name of your application that this label is being added to otherwise Traefik will see duplicates.
To show you a full example, we will add the label to an existing docker-compose.yml file for Adminer.
Now while in the same directory as the docker-compose.yml file, run the command docker-compose up -d and it should recreate the container for you with the latest labels. Now when you deploy your application you will be able to visit it by going to your domain with the app name as the subdomain (APP-NAME.DOMAIN.COM).
PLEASE NOTE
You can add multiple of these labels at once before finally deploying your application.
Traefik will now pick up that the app wants to be routed through the reverse proxy and should automatically set it up for you.
