Learn Traefik - Static Configuration

#Introduction

In episode 3 you ran Traefik with CLI flags. Now it is time to move to a more professional approach: static configuration in a file. Static configuration is every setting Traefik reads at startup — entrypoints, providers, API dashboard, logs, and certificate resolver.

Episode 4 explains the four ways to write static config, their priority order, and then practices the most important parts one by one. After this episode, you will have a traefik.yml file worth using as the basis for all subsequent experiments — and most importantly, a dashboard that is no longer open without authentication.

#Configuration Formats and Priority

#Four Ways to Write

Traefik accepts static configuration through four mechanisms, with priority from highest to lowest:

1. CLI arguments: --entrypoints.web.address=:80
2. Environment variables: TRAEFIK_ENTRYPOINTS_WEB_ADDRESS=:80
3. Config file: traefik.yml (YAML) or traefik.toml (TOML)
4. Traefik's built-in defaults

Rule of thumb: if a value is written in more than one place, the one with higher priority wins. The conversion from CLI to environment variable follows this pattern: the -- prefix is removed, dots become underscores, and letters are capitalized.

--entrypoints.web.address=:80
TRAEFIK_ENTRYPOINTS_WEB_ADDRESS=:80

A TOML example for comparison — a format that was popular in Traefik v2:

[api]
  dashboard = true
 
[entryPoints]
  [entryPoints.web]
    address = ":80"

For this series we consistently use YAML. TOML and YAML markup languages are both fully supported by Traefik.

#Entrypoints

#Definition and Usage

An entrypoint is Traefik's listen address: a combination of protocol, host, and port. Naming is free, but the common convention uses web for HTTP and websecure for HTTPS. Traefik v3 also supports separate TCP and UDP protocols, which we will cover in episode 18.

entryPoints:
  web:
    address: ":80"
  websecure:
    address: ":443"
  api:
    address: ":8080"

Later, each router declares which entrypoint it serves. The api entrypoint above is used specifically for the dashboard, so the dashboard cannot be reached through a public entrypoint. The configuration below shows the complete setup that will become the standard for this series:

api:
  dashboard: true
 
entryPoints:
  web:
    address: ":80"
  websecure:
    address: ":443"
  dashboard:
    address: ":8080"
 
providers:
  docker:
    exposedByDefault: false
 
log:
  level: INFO
  filePath: "/var/log/traefik/traefik.log"
 
accessLog:
  filePath: "/var/log/traefik/access.log"

#API and Dashboard

#Enabling and Securing

The Traefik API provides HTTP endpoints that expose the entire dynamic configuration at runtime. The dashboard is the graphical interface on top of that API. When enabled, both can be reached through any bound entrypoint — including public ones, so they must be secured.

The simplest way: put the dashboard on an internal entrypoint, then attach a BasicAuth middleware to the dashboard router. We will dissect this middleware in episode 9, but first see the pattern here:

# read by providers.file (episode 19)
http:
  routers:
    dashboard:
      rule: "Host(`traefik.localhost`) && PathPrefix(`/api`) || Host(`traefik.localhost`) && PathPrefix(`/dashboard`)"
      entrypoints:
        - dashboard
      service: api@internal
      middlewares:
        - auth
  middlewares:
    auth:
      basicAuth:
        users:
          - "admin:$apr1$H6uskkkW$IgXLP6ewTrSuBkPqGkHpv5"

This special router named dashboard points to the built-in service api@internal — Traefik's internal service that provides the dashboard. The Host and PathPrefix pair only allows dashboard traffic, and the auth middleware demands credentials before dashboard content is displayed.

#API Endpoints

Besides the dashboard, the API exposes useful endpoints for debugging:

/api/overview        -> component summary
/api/http/routers    -> list of active routers
/api/http/services   -> list of active services
/api/http/middlewares -> list of active middlewares

We will use these endpoints in episode 24 to inspect runtime configuration.

#Log Configuration

#Levels and Format

Traefik has two log streams: Traefik logs (internal activity) and access logs (logs of every request). Traefik logs have five levels: DEBUG, INFO, WARN, ERROR, and FATAL. For routine debugging, INFO is enough; DEBUG produces a very large output but is useful when tracing routing problems.

Access logs can use the Common format (default, one line per request) or JSON for machine parsing:

accessLog:
  filePath: "/var/log/traefik/access.log"
  format: json
  filters:
    statusCodes:
      - "200"
      - "5xx"
  fields:
    headers:
      names:
        User-Agent: keep

Above, we limit logs to status 200 and all 5xx, and keep the User-Agent header. File rotation can be done with logrotate on the host, or by letting Traefik write to stdout and delegating aggregation to an external tool — we will cover this in episode 24.

#Closing

Key takeaways:

• Configuration priority: CLI args, environment variables, file, then defaults.
• Entrypoints determine the listen port; routers are then bound to entrypoints.
• The dashboard must be secured: put it on an internal entrypoint and attach BasicAuth.
• The api@internal service is the gateway to the Traefik dashboard.
• Logs have two streams: Traefik logs and access logs, each available in JSON format.

In episode 5 next we will cover Docker Provider: Labels & Discovery — how Traefik finds containers, the traefik.http.* label structure, basic routing with Host and Path, load balancer service configuration, and the dynamically changing container lifecycle. This is where the auto-discovery magic begins.