502 Bad Gateway: nginx configured to use PHP-FPM Unix socket in multi-container setup

[abretz47]

tl;dr - run the following if you're facing this issue:

for f in \                  
  ./config/nginx/common/php.conf \
  ./config/nginx/common/wpfc-php.conf \
  ./config/nginx/common/block-wpadmin.conf
do
  cp "$f" "$f.bak"
  sed -i '' 's|fastcgi_pass unix:/run/php-fpm/fpm-www.sock;|fastcgi_pass php:9000;|g' "$f"

Issue

When bringing up the stack, nginx consistently returns 502 Bad Gateway. PHP-FPM is running correctly in its own container and listening on port 9000, but nginx is configured to connect to a Unix socket that does not exist inside the nginx container.

Observed Error

connect() to unix:/run/php-fpm/fpm-www.sock failed (2: No such file or directory)

Root cause

The nginx config files under config/nginx/common/ use:

fastcgi_pass unix:/run/php-fpm/fpm-www.sock;

However, in this project nginx and php-fpm run in separate containers and do not share a volume containing that socket path. As a result, nginx cannot reach PHP-FPM and returns 502.

Affected files:

config/nginx/common/php.conf

config/nginx/common/wpfc-php.conf

config/nginx/common/block-wpadmin.conf

Expected behavior
nginx should connect to PHP-FPM over Docker networking using TCP.

Suggested fix
Change all occurrences of:

fastcgi_pass unix:/run/php-fpm/fpm-www.sock;

to:

fastcgi_pass php:9000;