> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Middleware Manager

<div id="pangolin-toc-cta" className="pangolin-toc-cta-source">
  <Card title="Try free on Pangolin Cloud" icon="cloud" href="https://app.pangolin.net/auth/signup" arrow="true" cta="Sign up free">
    Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
  </Card>
</div>

<Note>
  This is a community guide and not officially supported. For issues, contributions, or bug reports, please use the [official GitHub repository](https://github.com/hhftechnology/middleware-manager).
</Note>

## What is Middleware Manager?

The **Middleware Manager** is a microservice that extends your existing traefik deployments.\
It provides a **web UI** to attach Traefik middlewares to resources without editing Pangolin itself.

#### Security Warning

Middlewares can strengthen security but also create vulnerabilities if misconfigured.

* Test in staging before production.
* Misusing forward authentication can leak credentials.
* Bad rate limiter configs may be bypassed.
* Header misconfigurations can expose apps to XSS/CSRF.
* Stacking too many middlewares impacts performance.
* Always check provider references (`@http` vs `@file`).

***

### Key Use Cases

* External authentication (Authelia, Authentik, JWT)
* Security headers and CSP policies
* Geographic IP blocking
* Rate limiting / DDoS protection
* Redirects & path rewrites
* CrowdSec and other security tool integrations

***

## Prerequisites

* A running **Pangolin v1.0.0+**
* Docker + Docker Compose
* Basic Traefik knowledge
* Admin access to your Pangolin host

***

## Step 1: Add Middleware Manager Service

Update your `docker-compose.yml`:

```yaml theme={"dark"}
middleware-manager:
  image: hhftechnology/middleware-manager:latest
  container_name: middleware-manager
  restart: unless-stopped
  volumes:
    - ./data:/data
    - ./config/traefik/rules:/conf
    - ./config/middleware-manager/templates.yaml:/app/config/templates.yaml  # Optional custom templates
  environment:
    - PANGOLIN_API_URL=http://pangolin:3001/api/v1
    - TRAEFIK_CONF_DIR=/conf
    - DB_PATH=/data/middleware.db
    - PORT=3456
  ports:
    - "3456:3456"
```

***

## Step 2: Create Required Directories

```bash theme={"dark"}
mkdir -p ./config/traefik/rules
mkdir -p ./config/middleware-manager
```

Move any dynamic configs into `./config/traefik/rules`.

***

## Step 3: Update Traefik Volumes & Providers

In your `traefik` service:

```yaml theme={"dark"}
volumes:
  - ./config/traefik:/etc/traefik:ro
  - ./config/letsencrypt:/letsencrypt
  - ./config/traefik/logs:/var/log/traefik
  - ./config/traefik/rules:/rules   # required
```

In `traefik_config.yml`:

```yaml theme={"dark"}
providers:
  file:
    directory: "/rules"
    watch: true
```

***

## Step 4: Start Services

```bash theme={"dark"}
docker compose up -d
```

***

## Step 5: Access the UI

Middleware Manager runs at:
👉 [http://localhost:3456](http://localhost:3456)

***

## Common Middleware Examples

### Rate Limiting

```yaml theme={"dark"}
middlewares:
  - id: "rate-limit"
    type: "rateLimit"
    config:
      average: 100
      burst: 50
```

### Security Headers

```yaml theme={"dark"}
middlewares:
  - id: "security-headers"
    type: "headers"
    config:
      customResponseHeaders:
        Server: ""
        X-Powered-By: ""
      browserXSSFilter: true
      contentTypeNosniff: true
      forceSTSHeader: true
      stsSeconds: 63072000
```

***

## Troubleshooting

* **Service does not exist** → Check `@http` or `@file` suffix in references
* **Middleware does not exist** → Verify config and required plugins
* **No changes applied** → Check Traefik logs, middleware priority, restart services
* **UI not showing resources** → Confirm `PANGOLIN_API_URL` and network connectivity
* **Database errors** → Check `./data` permissions, or reset `middleware.db`
* \*\*CrowdSec errors → Ensure the crowdsec container is running; middlewares fail if the service is down.
* **Protecting Pangolin itself** → Apply middlewares (e.g. geoblock, headers) directly on the websecure entryPoint to cover all traffic.
* **Applying to many services** → Attach middleware to entryPoints instead of individual resources to cover all subdomains at once.
* **TCP / SMTP with STARTTLS** → Not supported. Traefik cannot handle STARTTLS negotiation (only implicit TLS like SMTPS on 465).

***

## Final Notes

The Middleware Manager gives you a UI to work with Traefik’s powerful middleware ecosystem.

* Start with simple configs → test thoroughly → expand gradually.
* Use templates where possible.
* Always validate in staging before production.