Managing Load with the Traefik Queue Manager Plugin + Pangolin

Guides & Tutorials
, ,
1

:door: Managing Load with the Traefik Queue Manager Plugin + Pangolin

Traefik Queue Manager is a middleware plugin designed to control traffic spikes by queuing users when service capacity is exceeded. Combined with Pangolin and Middleware Manager, it’s a powerful solution for managing traffic overload.

This guide walks you through a minimal working implementation.

:light_bulb: Prerequisite: Set up the Traefik Dashboard to debug config issues.

:ledger: Features

  • Custom queue page
  • Configurable max users (maxEntries)
  • First-come, first-served access
  • Visual position and wait time tracking
  • Cookie-based or IP/UserAgent session tracking

:rocket: Step-by-Step Setup

Step 1: Add the Plugin via Plugin Hub

Enable the plugin by adding to traefik_config.yml:

experimental:
  plugins:
    traefik-queue-manager:
      moduleName: "github.com/hhftechnology/traefik-queue-manager"
      version: "v1.0.2"

Restart Traefik:

docker compose restart traefik

professional-queue
professional-queue867×557 32.9 KB

:camera: Screenshot: Traefik config with plugin block enabled:

Step 2: Prepare Your Queue Page

Create a directory for static assets:

mkdir -p ./public_html

Create public_html/queue-page.html with this content:

<!DOCTYPE html>
<html>
<body>
<h1>Your in a queue</h1>
<p>[[.Position]] - Current position in queue</p>
<p>[[.QueueSize]] - Total queue size</p>
<p>[[.EstimatedWaitTime]] - Estimated wait time in minutes</p>
<p>[[.RefreshInterval]] - Refresh interval in seconds</p>
<p>[[.ProgressPercentage]] - Visual progress percentage</p>
<p>[[.Message]] - Custom message</p>
</body>
</html>

Update your docker-compose.yml Traefik service:

volumes:
  - ./public_html:/var/www/html:ro

Restart Traefik:

docker compose restart traefik

Verify with:

docker exec -it traefik sh
ls /var/www/html

Step 3: Add Middleware Template

Append to middleware-manager/templates.yml:

- id: "traefik-queue-manager"
  name: "Traefik Queue Manager"
  type: "plugin"
  config:
    traefik-queue-manager:
      cookieName: queue-manager-id-random-number-here
      enabled: true
      maxEntries: 500
      queuePageFile: /var/www/html/queue-page.html
      sessionTime: 5m
      useCookies: "true"

adding-plugin-using-middleware
adding-plugin-using-middleware844×828 65.8 KB

:camera: Screenshot Queue Manager middleware visible in UI

Restart Middleware Manager:

docker compose restart middleware-manager

Step 4: Create a Protected Resource

If you don’t have one, create a temporary resource:

Add to docker-compose.yml:

python-http:
  image: python:3.11-slim
  container_name: python-http
  working_dir: /app
  command: python -m http.server 15000
  ports:
    - "15000:15000"
  restart: unless-stopped

In Pangolin:

  • Create resource mywebsite.yourdomain.com
  • Target service: python-http on port 15000
  • Attach the Traefik Queue Manager middleware in Middleware Manager

pangolin-resource
pangolin-resource1254×800 43 KB

:camera: Screenshot Resource setup screen in Pangolin

add-middleware-to-resource
add-middleware-to-resource827×896 44 KB

:camera: Screenshot add middleware in Middleware Manager

Step 5: Test It Out

Visit:

https://mywebsite.yourdomain.com

You should be allowed through because usage is below the threshold.

Now edit the middleware to simulate a queue:

"maxEntries": 1

Visit again in a second tab or incognito. You should see the queue page.

queue-message
queue-message692×274 8.38 KB

:camera: Screenshot Queue HTML page rendered with position and wait time

:sparkles: Wrap-Up

You now have a working example of the Traefik Queue Manager in action with:

  • HTML queue pages
  • Session management
  • Load control

:date: Want more? View advanced config options here: Plugin Page

:folded_hands: Thanks for Following Along!

You just implemented fair, graceful queuing with Traefik, Pangolin, and Middleware Manager. Perfect for launch days, flash sales, and peak usage moments.

Happy queueing! :globe_with_meridians: