Middleware Manager

Middleware Manager is a management UI and API layer for Traefik. It allows operators to attach Traefik middlewares, manage custom services, tune routers, and control plugins or mTLS from a single interface.

It works by using either Pangolin or Traefik as a data source. It automatically generates Traefik dynamic configuration via an API and creates an override API. Crucially, it does not disturb the original API; if you revert the original API in the Traefik file, it will restore all default routers and services.

Important: The middleware-manager container must remain running to keep the override middleware deployed.

The Middleware-Manager API provides a high-level surface for operators and integrators to manage middlewares, services, resources, and Traefik configurations. All API endpoints are prefixed with /api.

Security Warning: The API does not provide public authentication by default. If you expose this API, you must secure it at the network layer using a reverse proxy, firewall, or VPN.

The documentation site is built using Next.js and Fumadocs. Key files and routes include:

• lib/source.ts: Contains the content source adapter. The loader() function provides the interface for accessing content.
• lib/layout.shared.tsx: Contains shared layout options.
• app/(home): Route group for the landing page and other general pages.
• app/docs: The main documentation layout and pages.
• app/api/search/route.ts: The Route Handler responsible for search functionality.

To protect your services from overload:

• Rate Limiting & Circuit Breaking: Implement these via middlewares or services where supported.
• TCP Streams: If handling long-lived TCP streams, ensure you set appropriate timeouts on your Traefik entrypoints.

Middleware Manager operates by bridging your existing infrastructure with its own managed overrides:

• Reads: It pulls routers, services, and middlewares from your active data source (either Pangolin or the Traefik API).
• Writes: It creates an overrides API containing middlewares, router attachments, custom services, and mTLS plugin middlewares.
• Static Edits: It modifies your Traefik static configuration by adding or removing experimental.plugins.* blocks during plugin lifecycle operations.

Middleware Manager requires an active data source to manage overrides. You can switch the source via Settings → Active Data Source.

Data Source Options

• Pangolin: Select this if Pangolin is the authoritative owner of your Traefik configuration.
• Traefik: Select this if Traefik is the primary provider and you require direct control.

Note: Middleware Manager implements overrides by writing to Traefik's file provider directory (which defaults to /conf).

When implementing mutual TLS (mTLS), watch for these common failure points:

• Certificate Authority (CA): Verify that the CA path is correct. An incorrect path or missing mtlswhitelist plugin configuration will break TLS handshakes.
• Rule Granularity: Avoid over-broad mTLS rules or disabling verification, as this can expose internal services to unauthorized access.

Middleware-Manager allows you to define custom Traefik services to control how traffic is routed to backends. The following service types are supported:

• loadBalancer: Standard HTTP/TCP/UDP backends. Supports optional health checks, sticky sessions, and passHostHeader.
• weighted: Distributes traffic across multiple named services based on assigned weights.
• mirroring: Mirrors a specific percentage of traffic to secondary services for testing or shadowing.
• failover: Defines a primary/fallback pair that uses health checks to switch between targets.

The frontend is built with React, Vite, TanStack Query, and Zustand. The project structure follows these patterns:

• State Management: UI state is managed via Zustand stores in ui/src/stores/*. Data fetching and server state are handled by TanStack Query.
• API Integration: The client used to communicate with the backend is located in ui/src/services/api.ts.
• Component Organization:
  • Feature Pages: Specific feature implementations are found in ui/src/components/* (e.g., dashboard, resources, middlewares, plugins, security).
  • Common UI: Shared layouts and theme components are in ui/src/components/common and ui/src/components/ui.
• Type Safety: Keep API-related types in ui/src/types.

When contributing, favor TanStack Query for data management and Zustand for UI state.

When modifying the middleware stack, be aware of the following high-risk areas:

• ForwardAuth / BasicAuth: Ensure endpoints and secrets are correct to prevent user lockouts.
• Headers: Avoid overwriting the Host header or removing existing security headers, as this can break origin checks or weaken security.
• RateLimit: Calibrate thresholds carefully; thresholds that are too low can cause self-inflicted Denial of Service (DoS), while thresholds that are too high fail to protect services.
• Redirects/Rewrites: Validate regex patterns to prevent open redirects or accidental auth bypasses.
• Priority: Be cautious when raising router priority, as it can divert traffic to unintended routers.
• Custom Services: Ensure backend addresses are typed correctly and protocols (HTTP vs TCP) match the target service to prevent outages.