Edit Traefik rules files safely
Traefik reads two kinds of settings for your apps: rules files and Docker labels. This page shows which one an app uses, how to edit it, how to add your own middleware or a plugin, and how to go back after a bad edit.
Before you start
Section titled “Before you start”- Traefik is set up and running. See Set up Traefik.
- You have a terminal on your server. Commands start in your Docker folder. Run
cddto get there, or usecd YOUR_DOCKER_FOLDERand replaceYOUR_DOCKER_FOLDERwith your Docker folder path. HOSTNAMEin a path is your server’s hostname. In a command you can type$HOSTNAME.
Rules files or labels
Section titled “Rules files or labels”Most apps use a rules file. Five apps use labels instead.
| How the app is set up | Where it lives | Apps | After you edit |
|---|---|---|---|
| Rules file | appdata/traefik3/rules/HOSTNAME/app-NAME.yml |
Every app you install behind Traefik, and every app you add with Traefikify | Nothing. Traefik applies a saved change by itself. |
| Docker labels | The labels: lines in compose/HOSTNAME/NAME.yml |
Traefik, Authelia, Authentik, OAuth and TinyAuth | Recreate the app. |
For a container you added in custom.yml, you choose either way. See Protect a custom.yml app with Traefik and a login.
Keep rules files directly in the rules folder. Traefik does not watch subfolders. See Which files Traefik loads.
To understand how the two differ, read UDMS part 18: Docker labels vs file provider (manual setup).
Edit a rules file
Section titled “Edit a rules file”-
Copy the file to your home folder first. Replace
NAMEwith the app’s name.Terminal window sudo cp appdata/traefik3/rules/$HOSTNAME/app-NAME.yml ~/app-NAME.yml.bakKeep copies outside the rules folder. Traefik loads every
.yml,.yamland.tomlfile there, so a copy such asapp-NAME-old.ymlwould clash with the original’s router names. -
Open the file.
Terminal window sudo nano appdata/traefik3/rules/$HOSTNAME/app-NAME.yml -
Change what you need. See What an app file holds.
-
Save and close. In nano, press
Ctrl+O,Enter, thenCtrl+X. -
Check the log for errors.
Terminal window sudo grep -i error logs/$HOSTNAME/traefik/traefik.log | tail -n 20For more ways to read the log, see Read the Traefik logs.
What an app file holds
Section titled “What an app file holds”An app-NAME.yml file normally has one router and one service. Their names end in -rtr and -svc and must stay unique across all files. Edit only these lines:
| Line | What it does | Change it to |
|---|---|---|
rule: |
The address. The part before .{{env "DOMAINNAME_1"}} is the subdomain. |
A new subdomain. See Change the subdomain of an app you already installed. Your DNS must send it to your server. |
entryPoints: |
Where the app can be reached: websecure-external (internet) and websecure-internal (your LAN). A line starting with # is switched off. |
Use Proxy > Traefik > Manage Exposure instead of editing. Changes take effect immediately. Simple mode offers only Both. See Simple vs Advanced Traefik mode. |
middlewares: |
The login method, as one chain: chain-authelia, chain-authentik, chain-oauth, chain-tinyauth, chain-basic-auth or chain-no-auth. |
Another chain. Or use Security > Manage Auth. For a rules file app it needs no restart. For a labels app it recreates the container. See Choose a login method. |
url: |
Where Traefik sends the request: http://IP:PORT. It starts with https:// if you chose https in Traefikify. |
A new IP or port. |
To see these lines edited by hand, watch Traefik 3 guide: edit an app’s rules file at 11:33 (manual Docker Compose setup; Deployrr writes this file for you).
Add your own middleware
Section titled “Add your own middleware”A chain such as chain-basic-auth is shared. Every app that uses it changes when you edit it, and Deployrr can replace it (see Files Deployrr writes again). So put your own middleware in a new file with a name of your own.
-
Create a file in the rules folder. Do not start the name with
middlewares-orchain-. For example,my-extra.yml.Terminal window sudo nano appdata/traefik3/rules/$HOSTNAME/my-extra.yml -
Add your middleware. This example adds a response header. The name
my-headerand the header are yours to choose.http:middlewares:my-header:headers:customResponseHeaders:X-My-Header: "1" -
Save the file.
Now add it to an app.
App with a rules file. Add a line under middlewares: in app-NAME.yml, after the chain:
middlewares: - chain-basic-auth - my-headerApp with labels. Add the name to the middlewares= label, separated by a comma, with @file after it:
- "traefik.http.routers.traefik-rtr.middlewares=chain-basic-auth@file,my-header@file"Then go to Tools > Stack Manager > Recreate and pick the app from the numbered list. Recreating Traefik drops web connections for a few seconds. See Stack Manager.
Traefik runs middlewares in the order you list them.
To see a middleware file added to the rules folder and picked up without a restart, watch Traefik 3 guide: add a middleware file to the rules folder at 5:48 (manual setup; the video starts file names with middlewares-, which you should avoid here).
Edit labels in a compose file
Section titled “Edit labels in a compose file”-
Copy the file.
Terminal window sudo cp compose/$HOSTNAME/NAME.yml ~/NAME.yml.bak -
Edit it.
Terminal window sudo nano compose/$HOSTNAME/NAME.yml -
Recreate the app from Tools > Stack Manager > Recreate. Without it, the change does not apply.
Reinstalling Traefik, Authelia, OAuth or TinyAuth keeps its compose file and your label edits. Reinstalling Authentik replaces its compose file, so copy your label lines back afterwards. Deleting the app in Tools > Stack Manager removes the file, and a new install brings back the default labels. See What can overwrite or delete your changes.
Add a Traefik plugin
Section titled “Add a Traefik plugin”A plugin needs two parts: lines in Traefik’s compose file that load it, and a middleware in a rules file that uses it. Take the plugin’s name, module path, version and settings from its page in the Traefik plugin catalog.
-
Copy Traefik’s compose file.
Terminal window sudo cp compose/$HOSTNAME/traefik.yml ~/traefik.yml.bak -
Open it.
Terminal window sudo nano compose/$HOSTNAME/traefik.yml -
Find this line near the end of the
command:section, just beforeports::# - PLUGINS-PLACEHOLDER-DO-NOT-DELETELeave it as it is. The CrowdSec Traefik Bouncer adds its plugin lines below it. If the line is gone, the bouncer install shows an error and you have to add its lines yourself. Leave the other
PLACEHOLDERlines in this file alone too. -
Add your plugin’s lines below it, not below the
METRICS-PLACEHOLDERline just above it. Use the same six-space indent. Replacemypluginwith a short name of your own, and the module path and version with the ones from the plugin’s page:# - PLUGINS-PLACEHOLDER-DO-NOT-DELETE- --experimental.plugins.myplugin.modulename=github.com/AUTHOR/PLUGIN- --experimental.plugins.myplugin.version=v1.0.0Do not use the name
crowdsec. The CrowdSec Traefik Bouncer uses it. If you set up the bouncer already, its lines (a# CrowdSec Bouncer Plugincomment and twocrowdseclines) are below the placeholder too. Put yours on their own lines before or after them. The order does not matter. -
Save and close, then recreate Traefik. Web connections drop for a few seconds.
Terminal window dcrec traefikWithout the aliases, use Tools > Stack Manager > Recreate and pick Traefik.
-
Check the log for plugin errors. Traefik downloads plugins when it starts, so the server needs internet access.
Terminal window sudo grep -i plugin logs/$HOSTNAME/traefik/traefik.log | tail -n 20 -
Create a rules file with a name of your own, as in Add your own middleware, and use the plugin there. Under
plugin:, the name must match the one in the compose lines. The settings come from the plugin’s page.http:middlewares:my-plugin:plugin:myplugin:SETTING: VALUE -
Add
my-pluginto an app’smiddlewares:, as in Add your own middleware.
A wrong module path or version can stop Traefik from loading any plugin, including CrowdSec. If apps fail after this change, copy ~/traefik.yml.bak back and run dcrec traefik.
Your plugin lines stay when you run Traefik Preparation again or reinstall Traefik, because Deployrr reuses the compose file. Deleting Traefik in Tools > Stack Manager removes them. For the CrowdSec plugin’s own warnings, see Warnings during the Traefik Bouncer install.
Restore a file after a bad edit
Section titled “Restore a file after a bad edit”-
Copy your backup over the file.
Terminal window sudo cp ~/app-NAME.yml.bak appdata/traefik3/rules/$HOSTNAME/app-NAME.yml -
Wait a few seconds. Traefik loads the restored file by itself.
-
For a compose file with labels, copy its backup back the same way, then recreate the app. For Traefik itself:
Terminal window dcrec traefikWithout the aliases, see Which files Traefik loads for the full command.
No copy? Proxy > Traefik > Traefikify with the same name makes the file again. It does not bring back your edits. You enter the subdomain, IP, protocol, port, login and exposure again, and pick Yes at File Provider Exists. See Put any app behind Traefik with Traefikify. Or restore the file from a Deployrr backup. See Back up and restore your Docker folder.
Files Deployrr writes again
Section titled “Files Deployrr writes again”Copy a file before you run an action in this table.
| What you did | What happens to your edits |
|---|---|
| Reinstalled an app | Its rules file stays, with your edits. |
| Traefikify with a used name, then Yes at File Provider Exists | The file is made again. Your edits are gone. No keeps it. |
| Un-Traefikify | Deletes the file after you confirm. It recommends a backup from the Tools menu first. It may ask Remove from Dashboard?. |
| Traefik Preparation run again | Replaces seven files, listed below. |
| Installed Authelia, Authentik, OAuth or TinyAuth again | Replaces its middlewares-NAME.yml and chain-NAME.yml with no prompt. |
| Set up CrowdSec | Adds middlewares-crowdsec-bouncer.yml. At Add to Chain Files? it adds its middleware first in every chain-*.yml. |
| Domain Passthrough | Creates domain-*.yml files in the same folder. |
Traefik Preparation needs a Plus or Pro license. If it was done before, it warns “previous setup may be overwritten” and asks you to press Y or y. It then replaces:
tls-opts.ymlmiddlewares-basic-auth.ymlmiddlewares-buffering.ymlmiddlewares-rate-limit.ymlmiddlewares-secure-headers.ymlchain-basic-auth.ymlchain-no-auth.yml
A CrowdSec line you added to a chain is lost. Your app-NAME.yml files and files with your own names stay.
Check it worked
Section titled “Check it worked”- Open the app’s address in a private browser window.
- You see the app or its login page.
- The log shows no new error for the app. Run
traefiklogsand pressCtrl+Cto stop.
If you see a 404, 502 or Gateway Timeout, see One app behind Traefik shows 404, 502 or Gateway Timeout.

