More than once, while I was managing websites served by nginx on Debian, I needed features which were not available yet in the Debian packages — right now, current stable nginx version is 1.16, while Debian only provides 1.10-ish, which lacks for example some stream features which I want to use.
Conveniently enough, Nginx provides repositories for Debian 9 and 10, offering packages of the latest stable and mainline releases of nginx.
Now, you would think switching from one to the other is just a matter of adding the nginx repos and running apt update then apt upgrade, right?
Think again. 🙂
Now, there are not that many problems, but still, you’ll hit one of them sooner or later, so let’s go through these.
Backup your websites
Ok, that’s a pretty generic step, but I feel I cannot leave it out and assume you would do it anyway. You’re about to mess with your websites…
So now is the fscking time to back your websites up.
Actually, every so often is a good time to back your websites up. Every CMS worth its salt out there has some documented backup automation mechanism. Put that in place and test it before you go and upgrade your nginx.
Backup /etc/nginx/ and /var/www/
Debian nginx comes in three flavors, each one using its own package name: nginx-light, nginx-full and nginx-extras, each of which, as one would expect, provides more and more features.
On the other hand, nginx provides only one flavor : package nginx, which is one-size-fits-all.
Did you notice how the Debian and nginx package names are different? This means there is no upgrade path where you could just add the nginx repos and happily apt update then apt upgrade. You’ll have to uninstal the Debian nginx package then (add the nginx repos and) install the nginx one.
Aaaaand, purging the Debian packages will result in Debian trying to remove as much of /etc/nginx as it can and some of /var/www too. See where I am heading now?
Face it, you don’t want to lose any of your hard work on these nginx configuration and PHP and HTML and CSS files. And you certainly don’t want to have any difficulty in rolling back in case the switch does not work out eventually.
So back up your /etc/nginx/ and /var/www/ directories.
I know that you have backed up your websites, so you feel that you can skip backing up /var/www. Well, you can. Or you can back that up, it’s not that big, and you’ll have it in case you need it. Your pick.
Remove the Debian nginx package
You did install one of the three nginx packages, and now is the time to remove them. My personal favorite Linuxism for this is:
apt list --installed | grep nginx
(last visual check to the list of packages before saying goodbye)
apt purge $(apt list --installed | grep nginx | cut -d '/' -f 1)
Or you can, you know, just write the apt purge command manually.
You may prefer apt remove, which keeps the configuration files, to apt purge, which deletes them. I prefer purge here because the /etc/nginx/ structure for the nginx package is not the same as that for the Debian packages, so an apt remove would leave behind files which the new nginx wasn’t expecting.
… And, since I did that /etc/nginx/ backup, if I ever need one of the old files, I still have them anyway!
Install the nginx package
That’s documented well enough on the nginx website.
Fix the PHP FPM lock issue
Another difference between the Debian and nginx packages is that Debian runs its nginx processes under user www-data, whereas nginx runs them under user nginx.
The problem is, PHP FPM, the part which actually executes PHP scripts, runs as www-data and makes itself accessible only to user www-data. This was find for Debian nginx, not so for nginx nginx, which will be unable to talk to PHP FPM and therefore unable to get any PHP executed.
One possible fix is to make the PHP FPM lock file (which nginx uses to talk to PHP FPM) readable and writable by anyone. Be aware, though, that it lets any user on the system talk to PHP FPM as well.
A slightly more secure approach is to add user nginx to group www-data (the command is easy enough: adduser nginx www-data). This gives nginx the right to talk to PHP FPM, and still keeps any other user out.
Plus it solves any other situations where the web server process itself (rather than the PHP engine) would have to write content in /var/www/., although to be honest, I haven’t met any such case so far.
So: add user nginx to group www-data.
That’s about it
At this point, your websites should be running smoothly again, and all the newest nginx bells and whistles are now yours to play with. Have fun, and remember…
… Back up those websites from time to time!
