I’ve tended to shy away from upgrading Debian web servers in place, and I’m not sure why. Here’s how to upgrade to a newer distribution safely. I’m running the LAMP stack. The process will differ slightly with Nginx. My experience is all with Apache.
It takes around 5 minutes to upgrade a Debian LAMP server from an older version to the current version. Plan on running about eight commands; five to upgrade and three to enable the new PHP version.
Setting up your Debian Web server for the next distribution
Let’s get some preliminary stuff out of the way that may prevent you some trouble later.
Look up ahead of time what version of PHP your old and new versions run so you can switch appropriately. You can tell the old version with the command ls /etc/apache2/mods-enabled/php*
Write down the version you see. Also look up what the default version is in the new version, and write down that version too, because you’ll need that in the step after this. If any of this is confusing, don’t continue.
Next, check your web application to make sure it’s compatible with the new version of PHP. Debian is famous for not being aggressive with its PHP versions, but if I’ve learned anything as a security professional, it’s that corporations are good at moving slower than even Debian.
The time to find out about any compatibility issues is before you upgrade, not after.
Don’t read this next part until you’re really sure about your PHP version
Change /etc/apt/sources.list to change all references from the old distribution (buster in this example) to the new one (bullseye in this example):
sudo sed -i ‘s/buster/bullseye/g’ /etc/apt/sources.list
sudo sed -i ‘s/buster/bullseye/g’ /etc/apt/sources.list.d/*.list
The third command in this sequence, to set up for security updates, is a bit different. This one only mentions the new version you’re upgrading to.
sudo sed -i ‘s#/debian-security bullseye/updates# bullseye-security#g’ /etc/apt/sources.list
Replace the buster and bullseye versions with the versions appropriate for your situation.
If you prefer, you can also use a text editor to edit the files in /etc/apt/ manually.
Running the upgrade to bring your Debian web server to the next version
The next step is to perform the upgrade.
sudo apt update
sudo apt dist-upgrade
After the reboot, run these two commands, substituting the appropriate PHP versions for your upgrade scenario. The first command disables the old version and the second command enables the new one.
sudo a2dismod php7.2
sudo a2enmod php7.3
And now you can restart Apache.
sudo systemctl start apache2
If all goes well, you’re looking at less than five minutes of downtime.
How to fix Apache and PHP after the upgrade breaks it
Here’s the piece every other upgrade guide leaves out. Here’s how to upgrade Debian and fix Apache after it breaks. Because after it reboots, your web server is going to throw an error complaining about an invalid line in httpd.conf and php7.2.conf, or some other php.conf file.
To fix this, you just need to disable your old PHP version and enable the new one. This part is important since PHP is probably the main reason you’re looking to upgrade. Here’s how to do that.
ls /etc/apache2/mods-enabled to see what version of PHP you were running. Run the command php -v to find out the new version. Then run two commands, substituting the appropriate versions for what I have in my example.
systemctl start apache2
That’s your sequence. Run the upgrade, let the system reboot and Apache not come back, then switch over the PHP versions and start Apache.
Of course you want to have a backup of everything so you can revert. I did. In my case I had 7 minutes of downtime from the upgrade and reboot and subsequent PHP trouble. If I hadn’t had the PHP problems my downtime would have been shorter. I have an SSD and a very fast Internet connection so that helps.
Do the upgrade during a slow period and have your plan mapped out ahead of time. Go in knowing how you’re going to revert if it all goes sideways and exactly what you have to do to land the upgrade