Custom Middlewares

Traefik middlewares let you tweak requests before they reach your application — adding headers, rate limiting, IP whitelisting, and more.

How you apply a custom middleware in Coolify depends on your deployment type:

• Standard Applications — edit the Container Labels directly.
• Docker Compose — use a Coolify shorthand label or define labels in your docker-compose.yml.

Both approaches can reference middlewares defined inline (in Docker labels) or externally (in Traefik's dynamic configuration).

Standard Applications

For standard (non-Docker Compose) applications, you configure middlewares by editing the Container Labels in the Coolify UI.

Steps

1. Open your application in Coolify and scroll to the Container Labels section.

2. Uncheck Readonly labels so the label textarea becomes editable.

3. Add your middleware definition label(s). For example, to add rate limiting:

   traefik.http.middlewares.my-ratelimit.ratelimit.average=100
   traefik.http.middlewares.my-ratelimit.ratelimit.period=1m

4. Find the existing traefik.http.routers.https-0-<uuid>.middlewares=... line and append your middleware name to it:

   traefik.http.routers.https-0-<uuid>.middlewares=gzip,my-ratelimit

5. Save and redeploy.

Full Example

Given Coolify generated labels like:

traefik.enable=true
traefik.http.middlewares.gzip.compress=true
traefik.http.middlewares.redirect-to-https.redirectscheme.scheme=https
traefik.http.routers.http-0-abc123.entryPoints=http
traefik.http.routers.http-0-abc123.middlewares=redirect-to-https
traefik.http.routers.http-0-abc123.rule=Host(`app.example.com`) && PathPrefix(`/`)
traefik.http.routers.http-0-abc123.service=http-0-abc123
traefik.http.routers.https-0-abc123.entryPoints=https
traefik.http.routers.https-0-abc123.middlewares=gzip
traefik.http.routers.https-0-abc123.rule=Host(`app.example.com`) && PathPrefix(`/`)
traefik.http.routers.https-0-abc123.service=https-0-abc123
traefik.http.routers.https-0-abc123.tls.certresolver=letsencrypt
traefik.http.routers.https-0-abc123.tls=true
traefik.http.services.http-0-abc123.loadbalancer.server.port=3000
traefik.http.services.https-0-abc123.loadbalancer.server.port=3000

To add a custom headers middleware, add a definition and update the router:

traefik.http.middlewares.security-headers.headers.browserXssFilter=true
traefik.http.middlewares.security-headers.headers.contentTypeNosniff=true
traefik.http.middlewares.security-headers.headers.frameDeny=true
traefik.http.routers.https-0-abc123.middlewares=gzip,security-headers

Docker Compose Services

For Docker Compose deployments, Coolify provides a shorthand label that automatically injects your middleware into the router chain — no need to manually edit router labels.

Using the Coolify Shorthand

Add coolify.traefik.middlewares to your service labels:

services:
  myapp:
    image: nginx:alpine
    labels:
      - "traefik.http.middlewares.my-ratelimit.ratelimit.average=100"
      - "traefik.http.middlewares.my-ratelimit.ratelimit.period=1m"
      - "coolify.traefik.middlewares=my-ratelimit"

Coolify reads this label during deployment, extracts the middleware name, and appends it to the router's middleware chain alongside built-in middlewares like gzip.

For multiple middlewares, separate them with commas:

labels:
  - "coolify.traefik.middlewares=my-ratelimit,security-headers"

Using External Middlewares (@file)

If you have a middleware defined in Traefik's dynamic configuration, you can reference it by appending @file to its name. This avoids duplicating middleware definitions across multiple applications.

1. Define the Middleware in Dynamic Configuration

Go to Server → Proxy → Dynamic Configurations and create a new config file:

http:
  middlewares:
    my-ipallowlist:
      ipAllowList:
        sourceRange:
          - "192.168.1.0/24"
          - "10.0.0.0/8"

2. Reference It in Your Application

Standard Application — update the router middlewares line:

traefik.http.routers.https-0-abc123.middlewares=gzip,my-ipallowlist@file

Docker Compose — use the shorthand:

labels:
  - "coolify.traefik.middlewares=my-ipallowlist@file"

Common Middleware Examples

Rate Limiting

See Traefik RateLimit reference for all available options.

traefik.http.middlewares.my-ratelimit.ratelimit.average=100
traefik.http.middlewares.my-ratelimit.ratelimit.period=1m
traefik.http.middlewares.my-ratelimit.ratelimit.burst=50

Custom Headers

See Traefik Headers reference for all available options.

traefik.http.middlewares.security-headers.headers.browserXssFilter=true
traefik.http.middlewares.security-headers.headers.contentTypeNosniff=true
traefik.http.middlewares.security-headers.headers.frameDeny=true
traefik.http.middlewares.security-headers.headers.stsSeconds=31536000
traefik.http.middlewares.security-headers.headers.stsIncludeSubdomains=true

IP Whitelisting

See Traefik IPAllowList reference for all available options.

traefik.http.middlewares.my-ipwhitelist.ipallowlist.sourcerange=192.168.1.0/24,10.0.0.0/8

Redirects

For www/non-www redirects and domain forwarding, see the dedicated Redirects guide, which also covers Coolify's built-in Direction setting.

Label Escaping

When your middleware labels contain special characters like $ (common in basic auth hashes), Coolify provides an Escape special characters in labels checkbox in the Container Labels section.

When enabled, $ characters are escaped to $$ to prevent Docker from interpreting them as environment variable references.

Troubleshooting

Middleware Not Applied

• Standard app: Verify you added the middleware name to the traefik.http.routers.*.middlewares label. Defining the middleware alone is not enough — it must be referenced in the router.
• Docker Compose: Confirm the coolify.traefik.middlewares label is present and the middleware name matches exactly.
• Check Traefik's dashboard (if enabled) to see if the middleware is registered under your router.

Application Unreachable After Editing Labels

• If you edited labels on a standard application and broke routing, use the Reset Labels to Defaults button, re-enable Readonly labels, and redeploy.
• If using Docker Compose, check your docker-compose.yml syntax for quoting issues.

@file Middleware Not Found

• Ensure the dynamic config file is saved in the correct location and Traefik has reloaded it.
• Verify the middleware name in the config matches what you reference (case-sensitive).
• Check for YAML syntax errors in the dynamic config.