Introduction

During an in-place upgrade on a passbolt server such as moving from Debian 11 to Debian 12 or Ubuntu 20.04 to Ubuntu 24.04 for example, configuration files may need adjustments to ensure a seamless transition. One commonly encountered issue is a NGINX 502 Bad Gateway error when navigating to the passbolt instance post upgrade. Understanding why this occurs, what the error means and how to resolve it, ensures that the upgraded server runs smoothly and efficiently. 

Understanding NGINX 502 Bad Gateway error

This error is an HTTP status code that appears when a server acting as a gateway or proxy receives an invalid response from the upstream server. In this context, NGINX serves as the gateway, while php-fpm is the upstream server handling PHP requests. After an upgrade that changes the PHP version, the previously configured php-fpm socket or service name may no longer be valid, causing NGINX to fail when it tries to pass requests upstream.

Identifying the cause

A key setting in the NGINX configuration that links PHP processing to php-fpm is fastcgi_pass. This directive specifics how NGINX communicates with php-fpm, often through a Unix socket. After an OS upgrade, php-fpm service name or socket path changes to match the new PHP version. In this article, we are using Debian 11, before upgrading, it was /run/php/php7.4-fpm.sock. But after upgrading, it should be /run/php/php8.2-fpm.sock to match the new PHP version.

Verifying the current PHP version

Before adjusting NGINX configuration, it is important to confirm the installed PHP version. In this article, we are using Debian, the latest version is coming with PHP 8.2, but if you are upgrading Ubuntu to the latest version e.g., Ubuntu Noble, the PHP version should be PHP 8.3 so this is why it’s very important to double check before updating the configuration file. This can be done for example by running ls -ail /run/php on the terminal, it provides the current php-fpm sock version.

Updating the NGINX configuration

When the installed PHP version is confirmed, the NGINX configuration file for the passbolt server can be edited, this should be located in /etc/nginx/sites-enabled/nginx-passbolt.conf. Update the fastcgi_pass directory to reference the new php-fpm socket path. This ensures NGINX knows exactly where to send PHP requests.

Reloading NGINX

After adjusting the configuration file, reload NGINX to apply the changes

sudo systemctl reload nginx

This ensures that NGINX now points to the correct php-fpm socket, allowing PHP scripts to execute correctly and eliminating the 502 Bad Gateway error.

Conclusion

Upgrading distribution OS on a passbolt server requires a quick configuration check. Its needed to confirm that NGINX can still communicate properly with php-fpm and serve the passbolt instance without interruption. The simple configuration fix restores normal operations and sets the stage for a stable, well-maintened environment.