Debian 12 (Bookworm) was released in June 2023 for Linux computers. The new version features a massive number of updates, such as a new Linux kernel, new PHP version, LibreOffice and much more. Upgrading an operating system to a new major release is always somewhat distressful task, especially if you are upgrading a production server or a PC that is the primary workstation of someone. Here is our guide for upgrading Debian to version 12 with tips for systems running applications that rely on LAMP software packages (Linux, Apache, Mysql/Mariadb, PHP).

Before you start the upgrade

Major releases of Debian can only be upgraded from the previous version. The system you want to upgrade must be running on Debian 11 before you can start. Here is a guide for upgrading to Debian 11. Not sure which version you have? Type on the command line:
hostnamectl
If it doesn't run, type:
cat /etc/debian_version

Copy these two network configuration files into a safe place before starting the upgrade:

/etc/resolv.conf
/etc/network/interfaces

(Having a copy of resolv.conf saved my day because for some reason upgrade process deleted the existing resolv.conf).

To minimize package conflicts, check the status of current apt packages, and remove old ones:

dpkg --audit
apt clean
apt autoremove

If you believe available disk space could run low during the upgrade, check the status:
df

Perhaps there are packages you can remove? List installed packages:
apt list --installed

I rarely reboot our Linux servers or PCs, but at this stage - just before the actual upgrade I rebooted the computer.

The Debian 12 upgrade process

First, the apt package system has to be told that you want Debian 12 Bookworm software instead of Bullseye. This means editing a few lines in the configuration file /etc/apt/sources.list. Below is a list of key lines required by Debian. The principle is to replace bullseye with bookworm. Your sources.list may have more lines for additional packages. Also files in the sources.list.d -directory may point to additional packages. Here are the key lines you need:

deb http://deb.debian.org/debian/ bookworm main
deb http://security.debian.org/debian-security bookworm-security main
deb http://deb.debian.org/debian/ bookworm-updates main
deb http://deb.debian.org/debian bookworm non-free non-free-firmware
deb http://deb.debian.org/debian-security bookworm-security non-free non-free-firmware
deb http://deb.debian.org/debian bookworm-updates non-free non-free-firmware

(Thanks to https://www.debugpoint.com/upgrade-debian-12-from-debian-11/ for the list)

Now, let's start. Type the following on the command line:

apt update

The last lines of the output look like something below:

Reading package lists… Done
Building dependency tree… Done
Reading state information… Done
2069 packages can be upgraded. Run 'apt list --upgradable' to see them.

Next, type:

apt upgrade

You should see something like this:

1694 upgraded, 224 newly installed, 0 to remove and 375 not upgraded.
Need to get 1,526 MB of archives.
After this operation, 1,750 MB of additional disk space will be used.

Patience, it can take a long time to finish. Once it is done, you can run the major version upgrade:

apt full-upgrade

You should see something like:

375 upgraded, 123 newly installed, 46 to remove and 0 not upgraded.
Need to get 436 MB of archives.
After this operation, 325 MB of additional disk space will be used.
Do you want to continue? [Y/n]

Again, this process may take some time to finish.

If the upgrade completed without critical errors, reboot the system. Once it is up and running, verify the operating system version:

hostnamectl
or
cat /etc/debian_version

Troubleshooting

If you have problems with connecting to the network after the upgrade (the command line error message can be something like:
Temporary failure in name resolution
you may have lost your DNS configuration file. This is why the first thing to do before starting the upgrade was to backup the file/etc/resolv.conf. Now is the perfect time to recover the file in its original location.

Servers that are running a LAMP software may encounter critical errors because all the key packages for Apache, Mysql/Mariadb and PHP have been upgraded.

PHP seems to be the major casualty. You have to manually install PHP 8.2 and additional PHP modules that your system requires.

apt install php8.2

And the modules you need, such as ((which modules are needed depends on the applications and services you are running):

apt install php8.2-mysql
apt install php8.2-mbstring

Remember to restart the web server after these changes. If you are running Apache2:

systemctl restart apache2

We are running Wordpress CMS, so it was the first service we tested after PHP installation. Although Wordpress worked, we had a theme that completely broke the entire Wordpress when it was activated. The theme worked fine with PHP 7.4, but PHP 8.2 caused the theme to crash.

PHP 8.2 may break programs that ran fine earlier.

Updated on 2023-08-09: here is an articlethat lists major changes in PHP 8.2 compared to earlier version.

Upgrading to PHP 8.2 may not only break Wordpress themes, but Wordpress plugins as well. We have encountered two plugins so far that failed to run on PHP 8.2. The problems didn't instantly make themselves known, so identifying them required some research. The core Wordpress is compatible with PHP 8.2.

We have a number of tool programs and web applications written in PHP, and some of them started misbehaving after the upgrade to PHP 8.2. So far, we have identified two common problems in the PHP code of the programs we have: variable typesand timezone. PHP has been flexible with variable types so far, but now it requires a variable to stick to its type. Most often, the code we have corrected had undeclared or empty arrays. Surprisingly many programs rely they are running on the same timezone as the underlying operating system. Now, this timezone must be set in PHP - either in the PHP.ini file or in the program using a dedicated function.

Debian development team has written a thorough upgrade document that you can view here.