Proxy configuration (middlewares)

Manage

Infrastructure → Reverse proxy → Dynamic configuration (owner; admins read only)

Attach

Application → Domain tab → Middleware → Configure

Scope

Traefik dynamic configuration per proxy (host or remote server)

How it works

Traefik reads dynamic configuration from a directory and reloads every file that changes, without a restart. aoox keeps the YAML files you write in its database (the source of truth) and writes them to the proxy as user-<name>.yml. They are separate from custom certificates: aoox never touches certs.yml or the certificate files, and certificate handling never touches user- files.

• One list of files per proxy: pick aoox host or one of the remote servers at the top of the card.
• Only the http section is accepted: middlewares, routers, services, serversTransports. tls (certificates are managed under SSL certificates), tcp, udp and other keys are rejected with a clear message.
• Middleware, router and service names use lowercase letters, digits and - only, and must be unique per proxy (across enabled files).
• At most 64 KB per file. A disabled file stays in aoox but is removed from the proxy.

Creating a file

1. Infrastructure → Reverse proxy → Dynamic configuration

   Only the owner can change anything; admins can read the list and the file contents.

2. From a preset, or write your own

   From preset opens a small form and produces ready-to-save YAML in the editor (you can still edit it):

   Preset	Contents
   Basic auth	Username and password. Only a bcrypt hash is stored; the password never appears in the file or the audit log.
   Security headers	HSTS (over HTTPS only), nosniff, frame deny, referrer policy.
   Rate limit	Average, burst and period per source IP.
   IP allowlist	A validated list of addresses/CIDRs; everything else gets 403.
   Redirect www	Permanent redirect from www to non-www or the reverse. Attach it to the domain being redirected (www.example.com for to-non-www, example.com for to-www).

   Or New file to write the YAML yourself, e.g.:

   http:
     middlewares:
       header-aoox:
         headers:
           customResponseHeaders:
             X-Powered-By: aoox

3. Save

   aoox checks the YAML structure, writes the file to the proxy, waits a few seconds, then reads Traefik's log. If Traefik reports an error about the file, the change is rolled back automatically (the previous version is restored) and the error is shown verbatim.

Attaching to a domain

On the application's Domain tab every domain has a Middleware row with a Configure button. Pick middlewares from the enabled files on the proxy that serves that application (named like name@file). The order you switch them on is the order they run. It needs the developer role or above; viewers can only read. Saving recreates the application container with new labels (no build), like changing the certificate.

• Middlewares go on the domain's HTTPS router, and on the HTTP router for domains served over HTTP. The automatic http→https redirect does not use them.
• Domains with the same middleware list share a router; different lists are split automatically, so one domain's middlewares never affect another.
• A middleware that a domain uses cannot be disabled, deleted or renamed (409, the domain is named). Remove it from the domain first.
• A name that is not in an enabled file on that application's proxy is rejected (400).

Proxies created by an older aoox

Apply again

Apply again rewrites every enabled file to the proxy and removes user-* files that no longer exist in aoox. Use it after an instance restore (a restore brings back the file contents in the database but does not write the proxy volume), after a proxy or server was set up again, or if the files on the volume were changed outside aoox.

Read timeout and large uploads

aoox puts no limit on request body size in Traefik (no buffering middleware), so a 55 MB upload is not refused for its size. What can cut it off is Traefik's entrypoint readTimeout: the longest a client may take to send a whole request, body included. Traefik's default is 60 seconds; a slow connection that needs longer is disconnected before the application sees the full body.

• Set Proxy read timeout under Infrastructure → Environment (owner), or PROXY_READ_TIMEOUT in .env.dist: whole seconds (300) or a duration (300s, 5m), from 1 to 86400. Empty means Traefik's default; an invalid value is ignored with a warning in the API log.
• It is static proxy configuration, so it only takes effect when the proxy is installed again: use Reinstall proxy on the Reverse proxy page (a few seconds without service; certificates and routes are kept). The page shows the value the running proxy uses and warns when it differs from the setting.
• The setting belongs to the panel and is applied to every proxy aoox installs, including the ones on remote servers (reinstall those from Remote servers).
• Something in front of Traefik has its own limits. For example a Cloudflare-proxied (orange cloud) domain caps the request body by plan and gives up on a response after about 100 seconds, whatever you set here.

Limits

• Dynamic configuration only. Static Traefik options (entrypoints, log level, trusted IPs) cannot be changed here, except the read timeout described above.
• aoox only catches errors Traefik logs. A wrong value that is not reported (for example an invalid service URL) gets through, so test the result after saving.
• A valid configuration can still change routing for every domain on that proxy (your routers can collide with application routes). That is why only the owner can write.
• Remote servers: written the same way, but not tested on a real server yet; make sure the files you need exist on the destination server's proxy before moving an application.
• Files are per proxy and are not part of project export/import; domains created by an import have no middlewares (the import still succeeds when the source used them).
• Moving an application to another server cleans its domains' middlewares: only names defined by an enabled file on the destination proxy are kept, the rest are dropped (logged by the API; the application PATCH answer carries droppedMiddlewares when something was dropped). The files themselves do not move.

Common pitfalls

Next steps