The Problem

Managing a Traefik reverse‑proxy by hand means editing YAML files, reloading services, and tracking backups across many hosts. A mistake at 2 am can break traffic for an entire homelab.

What This Does

traefik-manager provides a self‑hosted web UI that abstracts the Traefik API and the static traefik.yml configuration. The Python Flask app in app.py implements the HTTP API (e.g., api_routes, api_agent_routes, api_git_backup_push). Core logic lives in the core/ package – settings (core/settings.py), file handling (core/config.py), Git backup (core/git.py), authentication (core/auth.py), and the Traefik client (core/traefik.py). A lightweight Go agent (agent/main.go) runs on remote nodes and forwards API calls, allowing the UI to manage multiple Traefik instances from a single container.

How It Is Wired

Execution starts when the Flask server is launched from app.py (the setup function at line 652). setup loads the secret key (_load_or_create_secret_key) and calls load_settings (called from 85 places) which reads the user config via core/config.py (read_config → yaml.load). Most UI actions flow through a small set of hub functions:

  • load_settings – central read of config/*.yml; 85 callers (e.g., route editors, backup jobs).
  • save_settings – writes the same files; 30 callers (settings wizard, backup restore).
  • post_form – processes HTML form submissions; 34 callers (route creation, middleware wizards).

When a route is toggled, api_route_raw_save calls _toggle_route → create_backup (via core/backups.py) → save_config (writes YAML). The Traefik client (core/traefik.py) uses _traefik_request → requests.get/post (network call) to fetch or push routers, services, and middlewares. The Go agent’s entry point (agent/main.go) registers HTTP handlers that forward calls to the central Flask API, enabling multi‑host management without exposing Traefik’s admin port directly.

The most‑connected internal modules are core/__init__.py (imported by 26 modules) and core/env.py (15 imports). Their stability directly affects the whole code base. No circular imports were detected, so changes to a hub module have a predictable blast radius.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/traefik-manager
cd traefik-manager

# Build and run the container (Dockerfile and docker‑compose.yml are provided)
docker compose up -d

Required configuration – copy .env.example to .env and adjust the variables referenced in app.py (e.g., COOKIE_SECURE, TRAEFIK_URL). For remote hosts, build the Go agent image (docker build -f agent/Dockerfile -t traefik-agent .) and run it with the same .env values; the UI will discover it via the agents endpoint.

Running locally without containers – install Python dependencies (pip install -r requirements.txt) and start the Flask app:

export FLASK_APP=app.py
flask run --port 5000

The UI is reachable at http://<host>:5000; the first‑run wizard creates the secret key and a backup directory under backups/.

Real‑World Use

A homelab operator runs a single traefik-manager container on a NAS. Each Docker host runs the lightweight Go agent (agent/main.go) as a sidecar. When a new service is deployed, the operator opens the UI, adds an HTTP route via the wizard, and clicks “Apply”. The UI writes the updated dynamic.yml, triggers a Git commit (core/git.py), and the agent calls the remote Traefik API to reload the configuration—all in under a minute and without manual YAML edits.

Code Health & Issues

Static analysis reported 12 actionable findings:

  • HIGH – Pin GitHub Actions to commit SHAs (.github/workflows/*).
  • HIGH – Add an npm lockfile for package.json.
  • HIGH – Re‑enable TLS verification (verify=False in app.py).
  • HIGH – Replace unsafe yaml.load with yaml.safe_load (core/config.py).
  • MEDIUM – Declare least‑privilege GITHUB_TOKEN permissions (.github/workflows/tests.yml).
  • MEDIUM – Enable Dependabot or Renovate.
  • MEDIUM – Pin the base Docker image by digest (Dockerfile).
  • MEDIUM – Add a dependency‑vulnerability scan step in CI.
  • MEDIUM – Set persist-credentials: false on checkout.
  • MEDIUM – Add a non‑root USER to the container image.

No critical findings were reported. The repository includes tests, CI, a license, and documentation, but the missing lockfile and the unsafe YAML loader are the most immediate production risks.

The Bottom Line

traefik-manager delivers a functional UI and backup workflow that removes manual YAML editing for Traefik, making it suitable for small‑to‑medium homelabs. The code base is reasonably modular, but hub modules (core/__init__.py, core/env.py) are large and the unsafe YAML loader plus disabled TLS verification are serious security gaps that should be fixed before production use. With the high‑severity health items addressed, the project offers a practical, container‑first solution for managing multiple Traefik instances.