Resolving WordPress Pretty Permalinks Behind a PHP-Farm Upstream
Building a Dockerized testing platform for PHP applications, particularly WordPress, often leads to a specific configuration headache: getting "pretty permalinks" to work when routing traffic through an upstream proxy like phpfarm. The core challenge lies in reconciling the need for clean URLs on the host machine with the requirement to pass those requests to different PHP versions running on separate ports.
In a standard standalone Nginx setup, handling WordPress rewrites is straightforward. You define a single location block that attempts to serve static files first, then falls back to index.php with the query arguments intact:
location / {
index index.php index.html index.htm;
try_files $uri $uri/ /index.php?$args;
}
However, when you introduce a proxy setup to serve different PHP versions from different containers, the logic shifts. If you simply wrap your existing location block with proxy_pass and try_files, Nginx treats the request differently depending on whether it can locate a physical file. When a user requests /about/, Nginx checks for that file, doesn't find it, and attempts to rewrite the URL to /index.php?/about/. Because try_files has already failed to find a static resource, the rewritten URI is sent to PHP-FPM. If your backend logic expects the path to be passed as a query parameter or if the internal routing fails because the file doesn't exist in the expected place, you end up with a 404 or a redirect loop.
The error log entry rewrite or internal redirection cycle while processing "/index.php" is a dead giveaway that Nginx is trying to resolve /index.php but finding it doesn't exist as a static file, causing it to attempt another rewrite. This happens because try_files logic runs before the proxy pass takes over for non-static requests.
To solve this, you must separate concerns: serve static assets directly from the Nginx root and only proxy dynamic requests that require PHP execution. The most robust approach is to define a specific block for .php files to ensure they are always proxied, while letting try_files handle the fallback logic for everything else.
Here is a configuration pattern that addresses the upstream routing without breaking the rewrite chain:
server {
listen 80;
index index.php index.html index.htm;
server_name 52.spaces.dev;
root /var/www;
# Serve static files and handle rewrites
location / {
try_files $uri $uri/ /index.php?$args;
}
# Explicitly proxy PHP files to the upstream
location ~ \.php$ {
proxy_pass http://phpfarm_52;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header X-Real-IP $remote_addr;
}
upstream phpfarm_52 {
server phpfarm:8052;
}
}
By explicitly handling .php files, you ensure that Nginx knows exactly where to send the request. If try_files fails to locate a static file or directory for /about/, it attempts the rewrite to /index.php?/about/. Since this URI now contains .php (conceptually, as part of the rewritten path), the second location block catches it and proxies it correctly.
One critical detail often overlooked is the root directive. In your original example, placing root /var/www; at the server level can interfere with how try_files resolves paths if not carefully managed. Ensure that the root points to a directory containing the actual WordPress files you want Nginx to serve statically (like images or CSS) before they hit PHP. If your Docker volumes mount the entire site to /var/www, this setup works seamlessly.
This structure allows your host machine to present clean URLs like http://52.spaces.dev/about/ while internally routing the request to the specific PHP version container defined in your upstream block. It maintains a single codebase for your configuration rules across different PHP versions, provided you simply update the upstream server definition and port number for each rule.