Configuring trusted proxies

Choose a TRUSTED_PROXY value

Set TRUSTED_PROXY on the fpm-nginx, fpm-apache, or frankenphp image:

services:
  php:
    image: serversideup/php:8.5-fpm-nginx
    ports:
      - 80:8080
    environment:
      # cloudflare (default), sucuri, local, or off
      TRUSTED_PROXY: "local"

"Private networks" means 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 127.0.0.0/8, ::1, and fd00::/8, which covers Docker networks. Every option except off includes them. If you run Traefik or Caddy in Docker behind Cloudflare, cloudflare already covers both.

Use local when your own reverse proxy is the only thing in front of the container. cloudflare won't work there. NGINX and Apache only read CF-Connecting-IP, which doesn't exist without Cloudflare. They keep the proxy's IP.

The cloudflare option reads CF-Connecting-IP because Cloudflare sets it on every request and proxies like Traefik pass it through unchanged. Many proxies rewrite X-Forwarded-For unless you configure them to trust Cloudflare's ranges.

What Laravel still needs

The web server passes the visitor's IP to PHP as REMOTE_ADDR. That makes request()->ip() correct with no Laravel configuration.

When your proxy terminates HTTPS, Laravel also needs to know the original scheme so it generates https:// URLs. Trust only the X-Forwarded-Proto header in Laravel's trusted proxy configuration:

use Illuminate\Http\Request;

->withMiddleware(function (Middleware $middleware) {
    $middleware->trustProxies(
        at: '*',
        headers: Request::HEADER_X_FORWARDED_PROTO,
    );
})

Keep the proxy chain closed

A trusted proxy configuration only protects you if traffic can't skip the proxy:

• Accept traffic only from your CDN. A client that connects straight to your reverse proxy can send a forged CF-Connecting-IP header, and the proxy passes it along. Allow only your CDN's IP ranges at the edge, for example with a firewall rule or Traefik's ipAllowList middleware.
• Match the option to your setup. Don't use cloudflare or sucuri unless traffic comes through that service.
• Expect FrankenPHP to resolve differently. FrankenPHP uses Caddy's trusted_proxies_strict mode, which reads X-Forwarded-For from right to left and stops at the first untrusted address. When every address in the chain is trusted (a client on a private network behind a private proxy), FrankenPHP reports the proxy's address, while NGINX and Apache report the leftmost address.

CDN IP ranges change. The ranges are part of the image, so pull new images regularly. If you depend on them, compare them with your provider's published list.

Add your own provider

For a provider that isn't built in, such as AWS ALB or Fastly, add a file to the image and set TRUSTED_PROXY to its name without the extension:

Include the private network ranges so container-to-container traffic still resolves. This example uses 3.0.0.0/8 as a stand-in; replace it with your provider's published ranges.

FROM serversideup/php:8.5-fpm-nginx

COPY --chmod=644 docker/trusted-proxy/nginx/aws-alb.conf /etc/nginx/trusted-proxy/aws-alb.conf

For Apache or FrankenPHP, copy the matching file to the path in the table above. To try a file without rebuilding, mount it read-only at the same path instead of using COPY.

Still seeing the proxy's IP

1. If the container's access log shows your proxy's address, that address isn't in the ranges for the option you chose. Pick another option, or add a file for your provider as shown above.
2. Check the header. Cloudflare sends CF-Connecting-IP; most other proxies send X-Forwarded-For.
3. If the access log is right but request()->ip() is wrong, check that Laravel isn't trusting X-Forwarded-For (see what Laravel still needs).