Middlewares
Configure middlewares for GoDoxy
Quick Start
| Method | Order | Use Case | Configuration |
|---|---|---|---|
| Entrypoint | Ordered | Global middlewares | config.yml |
| Middleware Compose | Ordered | Reusable configs | config/middlewares/*.yml |
| Docker Labels | Unordered* | Per-route | Container labels |
| Route Files | Unordered* | Per-route | Route files |
Set priority for unordered methods when order matters.
Basic Example
# Global middleware (entrypoint)
entrypoint:
middlewares:
- use: real_ip
header: X-Real-IP
from: [127.0.0.1, 192.168.0.0/16]
# Per-service (Docker labels)
services:
app:
labels:
proxy.myapp.middlewares.redirect_http.priority: 1
proxy.myapp.middlewares.cidr_whitelist.priority: 2
proxy.myapp.middlewares.cidr_whitelist.allow: 127.0.0.1, 192.168.0.0/16Naming Convention
Middleware names and options are case-insensitive: redirectHTTP, redirect_http, RedirectHttp are equivalent.
Applying Middlewares
Entrypoint & Middleware Compose
# Entrypoint (config.yml)
entrypoint:
middlewares:
- use: CloudflareRealIP
- use: CIDRWhitelist
allow:
- 127.0.0.1
- 223.0.0.0/8
# Middleware Compose (config/middlewares/whitelist.yml)
myWhitelist:
- use: CloudflareRealIP
- use: CIDRWhitelist
allow:
- 127.0.0.1
- 223.0.0.0/8Docker Labels
# Single line
proxy.#1.middlewares.{name}.{option}: { value }
# YAML block
proxy.#1.middlewares.{name}: |
{option}: {value}Route Files
myapp:
middlewares:
{ name }:
{ option }: { value }Reusing Compositions
# Docker labels
proxy.#1.middlewares.myWhitelist@file:
# Route file
myapp:
middlewares:
myWhitelist@file:
# Entrypoint
entrypoint:
middlewares:
- use: myWhitelist@fileBypass Rules
Bypass rules are used for bypassing middlewares in specific cases.
Examples
See Rules syntax for complete documentation.
Entrypoint Example
entrypoint:
middlewares:
- use: oidc
bypass:
- route pocket-id
- route immich & path glob(/api/*)
- route dockmon & path /api/agent/ws
- remote 192.168.0.0/16Docker Labels Example
proxy.#1.middlewares.oidc.bypass: |
- route pocket-id
- route immich & path glob(/api/*)
- route dockmon & path /api/agent/ws
- remote 192.168.0.0/16Route File Example
myapp:
middlewares:
oidc:
bypass:
- path glob(/api/*)
- remote 192.168.0.0/16Entrypoint Overlay Promotion
When an entrypoint middleware is active (e.g. oidc), you can add per-route bypass rules that are promoted into the entrypoint middleware for that specific route. This avoids the middleware being evaluated twice — once at the entrypoint level and again at the route level.
How It Works
A route-local middleware entry that contains only bypass and matches an existing entrypoint middleware name (case-insensitive, snake-agnostic) is treated as an overlay:
- The route's bypass rules are qualified with the route name and appended to the matching entrypoint middleware's bypass list for that route only
- The route-local overlay is consumed — it is not evaluated again as a separate middleware
- If the route entry has options beyond
bypass, it is not treated as an overlay and works as a normal route middleware instead
Entrypoint Configuration Example
entrypoint:
middlewares:
- use: oidcDocker Labels Example
# Entrypoint has OIDC enabled
# This route adds bypass rules for the entrypoint OIDC middleware
proxy.myapp.middlewares.oidc.bypass: |
- path glob(/public/*)
- path /healthRoute File Example
myapp:
middlewares:
oidc:
bypass:
- path glob(/public/*)
- path /healthWith the above configuration, requests to myapp matching /public/* or /health will bypass the entrypoint's OIDC middleware. The route-local oidc entry is consumed and not applied again.
Mixed Options (Not an Overlay)
If the route middleware entry contains options other than bypass, it is not promoted and works as a regular route middleware:
myapp:
middlewares:
oidc:
allowed_groups:
- admins
bypass:
- path glob(/public/*)In this case, oidc is applied as a normal route middleware with both allowed_groups and bypass. The entrypoint OIDC middleware still applies separately.