Traefik Manager

Appearance

SupportStar

Environment Variables ​

All supported environment variables for Traefik Manager.

Precedence ​

Each variable below is labelled with one of these:

LabelBehaviour
OverridesEnv always wins. AUTH_ENABLED and ADMIN_PASSWORD only.
SeedsUsed on first start only. Once the setting is saved, manager.yml wins - even if you clear the field.
FallbackThe Settings field wins while it has a value. Clear it and the variable takes over.
-Env-only, never written to manager.yml.

Adding a Seeds variable to an existing install does nothing. Change the value in Settings, or delete the key from manager.yml and restart.

Quick Reference ​

Connection & Traefik ​

VariableDefaultPrecedenceDescription
TRAEFIK_API_URLhttp://traefik:8080Seeds traefik_api_urlTraefik API URL
TRAEFIK_API_USER(unset)Seeds traefik_api_userUsername for Traefik API basic auth
TRAEFIK_API_PASSWORD(unset)Seeds traefik_api_passwordPassword for Traefik API basic auth (stored encrypted)
TRAEFIK_INSECURE_SKIP_VERIFYfalse-Skip TLS certificate verification when calling the Traefik API (for self-signed certs)
REQUESTS_CA_BUNDLE/etc/ssl/certs/ca-certificates.crt-CA bundle for outbound HTTPS, so mounted private CAs are trusted

Authentication ​

VariableDefaultPrecedenceDescription
COOKIE_SECUREfalse-Mark session cookie as Secure - required for HTTPS
AUTH_ENABLEDtrueOverrides auth_enabledSet to false to disable built-in login entirely
ADMIN_PASSWORD(unset)Overrides password_hashAdmin password in plain text

Routes & Domains ​

VariableDefaultPrecedenceDescription
DOMAINSexample.comSeeds domainsComma-separated base domains for the Add Route form
CERT_RESOLVERcloudflareSeeds cert_resolverDefault ACME resolver name. Use none for external certs

Config Files ​

VariableDefaultPrecedenceDescription
CONFIG_DIR(unset)-Directory - all .yml and .yaml files loaded automatically
CONFIG_PATHS(unset)-Comma-separated list of config file paths
CONFIG_PATH/app/config/dynamic.yml-Single config file (default)
BACKUP_DIR/app/backups-Directory for timestamped config backups
BACKUP_KEEP_COUNT0Seeds backup_keep_countKeep only the last N .bak files per config file (0 = keep all)
SETTINGS_PATH/app/config/manager.yml-Path to the TM settings file

Static Config & Restart ​

VariableDefaultPrecedenceDescription
STATIC_CONFIG_PATH(unset)Fallback static_config_pathTraefik static config - required for the Plugins tab and Static Config editor
RESTART_METHODproxy-proxy, socket, or poison-pill
TRAEFIK_CONTAINERtraefik-Container name for proxy and socket restart methods
DOCKER_HOST(unset - uses /var/run/docker.sock)-Docker socket URL - set to tcp://socket-proxy:2375 for proxy method
SIGNAL_FILE_PATH/signals/restart.sig-Signal file path for poison-pill method

Monitoring ​

VariableDefaultPrecedenceDescription
ACME_JSON_PATH/app/acme.jsonFallback acme_json_pathPath to acme.json for the Certificates tab. Accepts several files comma-separated, or a directory
ACCESS_LOG_PATH/app/logs/access.logFallback access_log_pathPath to access log for the Logs tab
PLUGINS_DIR(unset)-Adds Traefik's plugins directory to the paths TM is allowed to read. Not needed for the Plugins tab, which reads experimental.plugins from the static config
GEOIP_DB_PATH(auto-downloaded)Fallback geoip_db_pathPath to a custom GeoIP .mmdb for IP geolocation
CROWDSEC_LAPI_URL(unset)Fallback crowdsec_lapi_urlCrowdSec LAPI base URL (e.g. http://crowdsec:8080)
CROWDSEC_API_KEY(unset)Fallback crowdsec_api_keyCrowdSec bouncer API key, reads decisions (stored encrypted)
CROWDSEC_MACHINE_ID(unset)Fallback crowdsec_machine_idCrowdSec machine login, reads alerts and enables unban
CROWDSEC_MACHINE_PASSWORD(unset)Fallback crowdsec_machine_passwordPassword for the machine login (stored encrypted)
CROWDSEC_CLIENT_CERT(unset)Fallback crowdsec_client_certPath to a TLS client certificate for a LAPI behind mTLS, replaces the API key and machine login
CROWDSEC_CLIENT_KEY(unset)Fallback crowdsec_client_keyPath to the client certificate's private key
CROWDSEC_CA_CERT(unset)Fallback crowdsec_ca_certPath to the CA certificate that signed the LAPI's own certificate (private PKI)
CROWDSEC_READ_TIMEOUT20-Seconds to wait for the LAPI to answer. Capped at 25
CROWDSEC_CONNECT_TIMEOUT5-Seconds to wait for the TCP/TLS connection itself
CROWDSEC_ALERT_LIMIT500-How many of the most recent alerts to read. 0 reads every alert, which is slow on a large LAPI

Agents ​

VariableDefaultPrecedenceDescription
AGENT_API_RATE_LIMIT30Seeds agent_api_rate_limitStored in manager.yml but not enforced in this release. The agent's own limit is TMA_RATE_LIMIT, set on the agent - see Agent

Security ​

VariableDefaultPrecedenceDescription
SECRET_KEY(auto-generated)-Flask session signing key
INACTIVITY_TIMEOUT_MINUTES120-Log out after this many minutes of inactivity
OTP_ENCRYPTION_KEY(auto-generated)-Fernet key for every secret stored encrypted in manager.yml
PROXY_FIX_HOPS1-Number of trusted proxy hops in front of Traefik Manager for X-Forwarded-For
LOG_LEVELINFO-Python log level: DEBUG, INFO, WARNING, ERROR

Connection & Traefik ​

TRAEFIK_API_URL ​

Default: http://traefik:8080
Seeds: traefik_api_url

The URL of the Traefik API. Must be reachable from the host running Traefik Manager.

yaml
environment:
  - TRAEFIK_API_URL=http://traefik:8080

TRAEFIK_API_USER / TRAEFIK_API_PASSWORD ​

Default: (unset)
Seeds: traefik_api_user / traefik_api_password (password stored encrypted)

HTTP Basic Auth credentials for the Traefik API. Set them when api.insecure: false and basic auth is configured on the Traefik dashboard. Both are required together.

Can also be set via Settings → Connection without a restart; leave the password blank there to keep the existing value.

Authentication ​

Default: false

Set to true when Traefik Manager is served over HTTPS.

yaml
environment:
  - COOKIE_SECURE=true

WARNING

If you are behind a reverse proxy with HTTPS and do not set this, logins will fail silently.

AUTH_ENABLED ​

Default: true
Overrides: auth_enabled

Set to false to disable the built-in login entirely. Use when TM is protected by an external auth provider (Authentik, Authelia, Traefik basicAuth, etc.). Only true/1/yes and false/0/no are recognised; anything else falls through to manager.yml.

yaml
environment:
  - AUTH_ENABLED=false

DANGER

When disabled and OIDC is off, the UI is fully open. Only use this behind another authentication layer.

ADMIN_PASSWORD ​

Default: (unset)
Overrides: password_hash

Set the admin password in plain text. Useful for scripted deployments.

yaml
environment:
  - ADMIN_PASSWORD=mysecretpassword

INFO

When set, the in-UI password change, flask reset-password and 2FA are all bypassed. Remove the variable to switch back to manager.yml-managed passwords.

Routes & Domains ​

DOMAINS ​

Default: example.com
Seeds: domains

Comma-separated list of base domains shown in the Add Route form. A form convenience only - it does not affect Traefik configuration, TLS, or routing. Domains found in existing routes are added to the form automatically, and the form's + chip accepts any other domain, so this list is optional.

yaml
environment:
  - DOMAINS=example.com,home.lab

CERT_RESOLVER ​

Default: cloudflare
Seeds: cert_resolver

One or more ACME cert resolver names, comma-separated. The first is the default for new routes. Each route can override this individually in the Add/Edit Route form.

Set to none if you manage certificates externally (cert files, internal CA, tls.yml). Routes will use tls: {} with no certResolver.

yaml
environment:
  - CERT_RESOLVER=letsencrypt

  - CERT_RESOLVER=letsencrypt, cloudflare

  - CERT_RESOLVER=none

Config Files ​

CONFIG_DIR, CONFIG_PATHS, CONFIG_PATH ​

Traefik Manager can manage one or many dynamic config files. Three variables control this in priority order:

CONFIG_DIR  >  CONFIG_PATHS  >  CONFIG_PATH

Only one should be set. When multiple config files are loaded, a Config File dropdown appears in the Add/Edit Route and Middleware forms. CONFIG_DIR also adds a + New file... option to create files on the fly.

CONFIG_DIR ​

Default: (unset)

Point to a directory and every .yml and .yaml file inside it, including subdirectories, is loaded automatically.

yaml
environment:
  - CONFIG_DIR=/app/config/traefik
volumes:
  - /host/traefik/config:/app/config/traefik

CONFIG_PATHS ​

Default: (unset)

Comma-separated list of full config file paths. Good for 2-5 named files.

yaml
environment:
  - CONFIG_PATHS=/app/config/routes.yml,/app/config/services.yml
volumes:
  - /host/routes.yml:/app/config/routes.yml
  - /host/services.yml:/app/config/services.yml

CONFIG_PATH ​

Default: /app/config/dynamic.yml

Single config file. Default for most setups.

yaml
environment:
  - CONFIG_PATH=/data/traefik/dynamic.yml
volumes:
  - /path/to/traefik/dynamic.yml:/data/traefik/dynamic.yml

BACKUP_DIR ​

Default: /app/backups

Where timestamped backups are written before every config save.

yaml
environment:
  - BACKUP_DIR=/data/backups
volumes:
  - /path/to/backups:/data/backups

BACKUP_KEEP_COUNT ​

Default: 0 (keep all)
Seeds: backup_keep_count

How many timestamped .bak files to keep per config file. Older ones are pruned after each backup. On the host this is also Settings → Backups; on a remote agent it is set via this variable.

yaml
environment:
  - BACKUP_KEEP_COUNT=30

SETTINGS_PATH ​

Default: /app/config/manager.yml

Path to the Traefik Manager settings file. Its directory also holds the companion files - agents.yml, templates.yml, notifications.yml, dashboard.yml, .secret_key and .otp_key.

yaml
environment:
  - SETTINGS_PATH=/data/manager.yml
volumes:
  - /path/to/manager.yml:/data/manager.yml

Static Config & Restart ​

If TM can reach the Docker socket, it reads the traefik-manager.restart-method and traefik-manager.static-config labels off your Traefik container at startup and uses them for any of these variables you left unset.

STATIC_CONFIG_PATH ​

Default: (unset)
Fallback: static_config_path

Path to Traefik's static config (traefik.yml or traefik.toml). Required for the Plugins tab and Static Config editor - both stay unavailable until this or the Settings field is set. Mount read-write (no :ro) to allow editing. Can also be set via Settings → System Monitoring → File Paths without a restart.

yaml
environment:
  - STATIC_CONFIG_PATH=/app/traefik.yml
volumes:
  - /path/to/traefik.yml:/app/traefik.yml

RESTART_METHOD ​

Default: proxy

How TM restarts Traefik after static config changes. Drives the Restart button in the Static Config editor.

ValueDescription
proxyVia a Docker socket proxy sidecar (recommended)
socketVia a directly mounted Docker socket
poison-pillWrites a signal file; Traefik's healthcheck detects it and restarts
yaml
environment:
  - RESTART_METHOD=proxy

See Static Config for full compose snippets for each method.

TRAEFIK_CONTAINER ​

Default: traefik

The name of the Traefik container to restart. Used by the proxy and socket restart methods.

yaml
environment:
  - TRAEFIK_CONTAINER=traefik

DOCKER_HOST ​

Default: (unset - uses /var/run/docker.sock)

Docker socket URL. Set to tcp://socket-proxy:2375 when using the proxy restart method.

yaml
environment:
  - DOCKER_HOST=tcp://socket-proxy:2375

SIGNAL_FILE_PATH ​

Default: /signals/restart.sig

Signal file path for the poison-pill restart method. Must be on a shared volume between TM and Traefik.

yaml
environment:
  - SIGNAL_FILE_PATH=/signals/restart.sig

Monitoring ​

ACME_JSON_PATH ​

Default: /app/acme.json
Fallback: acme_json_path

Path to Traefik's acme.json. Required for the Certificates tab. Can also be set via Settings → System Monitoring → File Paths without a restart.

Traefik writes one storage file per certificate resolver. Give them comma-separated, or point this at a directory and every .json file in it is read:

yaml
# comma-separated
- ACME_JSON_PATH=/letsencrypt/ovh.json,/letsencrypt/lan.json
# or a directory
- ACME_JSON_PATH=/letsencrypt

Certificates from every file are shown together, each tagged with the file it came from.

yaml
environment:
  - ACME_JSON_PATH=/letsencrypt/acme.json
volumes:
  - /path/to/acme.json:/letsencrypt/acme.json:ro

ACCESS_LOG_PATH ​

Default: /app/logs/access.log
Fallback: access_log_path

Path to Traefik's access log. Required for the Logs tab. Enable access logging in your Traefik static config first:

yaml
accessLog:
  filePath: /var/log/traefik/access.log
yaml
environment:
  - ACCESS_LOG_PATH=/logs/access.log
volumes:
  - /path/to/access.log:/logs/access.log:ro

GEOIP_DB_PATH ​

Default: (auto-downloaded to /app/config/geoip/dbip-country-lite.mmdb, next to manager.yml. The location follows SETTINGS_PATH, not CONFIG_DIR.)
Fallback: geoip_db_path

Path to a MaxMind DB format (.mmdb) GeoIP database for IP geolocation in the Logs and CrowdSec tabs. Leave unset to use the free DB-IP Lite country database TM downloads automatically; set it to use your own (e.g. MaxMind GeoLite2). Geolocation must be enabled in Settings → Interface → Geolocation.

yaml
environment:
  - GEOIP_DB_PATH=/data/GeoLite2-Country.mmdb
volumes:
  - /path/to/GeoLite2-Country.mmdb:/data/GeoLite2-Country.mmdb:ro

CROWDSEC_LAPI_URL ​

Default: (unset)
Fallback: crowdsec_lapi_url

Base URL of the CrowdSec Local API. Required to enable the CrowdSec tab, together with a bouncer API key, machine credentials, or a client certificate. The matching field in Settings → System Monitoring → CrowdSec takes priority.

yaml
environment:
  - CROWDSEC_LAPI_URL=http://crowdsec:8080

CROWDSEC_API_KEY ​

Default: (unset)
Fallback: crowdsec_api_key

CrowdSec bouncer API key, used to read decisions. Generate one with cscli bouncers add traefik-manager inside the CrowdSec container.

yaml
environment:
  - CROWDSEC_API_KEY=your-bouncer-key

CROWDSEC_MACHINE_ID / CROWDSEC_MACHINE_PASSWORD ​

Default: (unset)
Fallback: crowdsec_machine_id / crowdsec_machine_password

CrowdSec machine credentials. Required to read alerts and to unban (delete decisions) - bouncer keys get 403 access forbidden on those endpoints. Alerts are where every attack card on that tab comes from, so without these the tab can only show the bans already in force. The two credentials are complementary rather than tiered: CrowdSec refuses the machine token on /v1/decisions, so CROWDSEC_API_KEY is still needed alongside these. Create a machine with cscli machines add traefik-manager --auto -f- and copy the login / password from the output.

yaml
environment:
  - CROWDSEC_MACHINE_ID=traefik-manager
  - CROWDSEC_MACHINE_PASSWORD=your-machine-password

If the password contains a $, escape it as $$ in docker-compose.yml.

CROWDSEC_CLIENT_CERT / CROWDSEC_CLIENT_KEY / CROWDSEC_CA_CERT ​

Default: (unset)
Fallback: crowdsec_client_cert / crowdsec_client_key / crowdsec_ca_cert

Mutual TLS for the LAPI connection. If your LAPI authenticates bouncers and machines with client certificates (tls auth, bouncers_allowed_ou / agents_allowed_ou), point these at the PEM files mounted into the container. The certificate replaces the API key for decisions and the machine login for alerts - one certificate covers both when its OU is allowed on both sides, and the LAPI auto-provisions the bouncer and machine on first contact. CROWDSEC_CA_CERT verifies the LAPI's own server certificate when it comes from a private PKI. Certificate, API key and machine credentials can be mixed; any one of them makes the tab configured.

yaml
environment:
  - CROWDSEC_LAPI_URL=https://crowdsec:8080
  - CROWDSEC_CLIENT_CERT=/certs/tm-client.crt
  - CROWDSEC_CLIENT_KEY=/certs/tm-client.key
  - CROWDSEC_CA_CERT=/certs/ca.crt
volumes:
  - ./certs:/certs:ro

CROWDSEC_READ_TIMEOUT / CROWDSEC_CONNECT_TIMEOUT ​

Defaults: 20 / 5 seconds

How long to wait for the CrowdSec LAPI. Raise the read timeout if the CrowdSec tab reports the LAPI as unreachable on an instance that is simply busy. It is capped at 25 because the web worker is recycled at 30 - a higher value would be killed before it could return.

yaml
environment:
  - CROWDSEC_READ_TIMEOUT=25

CROWDSEC_ALERT_LIMIT ​

Default: 500

How many of the most recent alerts the CrowdSec tab reads, newest first. The default keeps the tab responsive on a LAPI holding a large community blocklist. Set it to 0 to read every alert the LAPI still retains - on a large instance that can take longer than the read timeout allows, which is what the limit exists to prevent.

yaml
environment:
  - CROWDSEC_ALERT_LIMIT=1000

Decisions are not limited. They are read through the LAPI's own streaming endpoint, which sends the full set once and then only what changed, so a refresh stays cheap no matter how many decisions the LAPI holds.

Security ​

SECRET_KEY ​

Default: (auto-generated and persisted as .secret_key alongside SETTINGS_PATH)

Flask session signing key. Set this to keep sessions alive across container restarts without re-login.

yaml
environment:
  - SECRET_KEY=your-random-32-byte-hex-string

Generating a key

bash
python3 -c "import secrets; print(secrets.token_hex(32))"

OTP_ENCRYPTION_KEY ​

Default: (auto-generated and stored as .otp_key alongside SETTINGS_PATH)

Fernet key for every secret TM stores encrypted: the TOTP secret, Traefik API password, OIDC client secret, webhook password, CrowdSec credentials, git backup token and agent API keys.

yaml
environment:
  - OTP_ENCRYPTION_KEY=your-32-byte-url-safe-base64-key

Generating a key

bash
python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

WARNING

Lose this key and every stored secret becomes unreadable - 2FA must be re-enrolled and the other credentials re-entered. Back up .otp_key alongside your config volume.

PROXY_FIX_HOPS ​

Default: 1

How many trusted reverse-proxy hops sit in front of Traefik Manager. TM reads the client IP from the right of X-Forwarded-For; this value is how many positions it trusts. With a single proxy in front (Traefik → app) the default of 1 is correct. With two hops (e.g. Cloudflare → Traefik → app) the app's own login and audit logs would otherwise record the intermediate proxy's IP - set it to 2.

The active value is shown in the startup log as Trusted Hops and in the Client IP Diagnostic.

yaml
environment:
  - PROXY_FIX_HOPS=2

WARNING

Only count hops you actually control. Each trusted hop is one more X-Forwarded-For entry a client could forge, so setting this higher than your real proxy chain lets callers spoof their source IP past the login rate-limiter and audit log. Set it to 0 to ignore X-Forwarded-For entirely and use the direct connection IP.