Upgrading Sympl

This article is Beta Documentation. It may have missing elements, or be unclear in places.
Please feel free to make corrections or amendments, or ask for help on the Sympl Forum

Upgrading Sympl versions is a little more complicated than a standard Debian upgrade, but has been tested throughly with servers using the Mythic Beasts Debian/Sympl images.

Unfortunately we can't support upgrades on other hosting providers, as there tend to be other packages installed on the images, and you may have other prompts which can render the system unusable.

Note that this is different the the typical "update" via running sympl update which will update the Sympl to the most recent versions of each package on the same major version, while this "upgrade" is for upgrading Sympl and Debian major versions (ie: 10 to 11).

Upgrades of Debian Stretch (Sympl 9) and Raspbian/Raspberry Pi OS are not supported at this time.

If you have installed any other packages yourself, you may be given other prompts, and these additional packages may have compatibility problems, but you should be able to find support for these other packages.

Assumptions

This guide makes the following assumptions:

• You're familiar with SSH and running commands as the root user.
• You're using a Mythic Beasts virtual or dedicated server.
• Sympl was installed either from an image, or using the installer.
• If you have installed any other packages yourself, you can answer their upgrade questions.
• All sites are confirmed to be compatible with the new [PHP] and [MariaDB] versions.
• You're prepared for 30-60 minutes downtime on the server while the upgrade takes place. You may with to put critical sites into a maintenance mode before starting to ensure no changes take place.
• You have read this entire page before you start the upgrade!

If any of the above aren't true, you can continue, but you may run into problems or break the server in unusual ways, and this is not a configuration we can support.

Before starting

• As with any major changes, you should first ensure that you have full backups seperate form the existing server, they contain all the relevant information and you can restore from them in the event the process goes wrong. If using the built-in Sympl backups, ensure you have an off-server copy of the full /var/backups directory.
• Apply any pending upgrades for the current setup

sudo apt -y update
sudo apt -y upgrade
sudo apt -y dist-upgrade
sudo sympl update

• Reboot the server to ensure it is working normally and you have a stable platform for the update.

shutdown -r now

• Where possible, put any sites into maintenance mode to ensure no changes are lost.
• Take a final backup before starting the upgrade process. If using Sympl backups, use sudo backup2l -b to make a new backup, then ensure you have a fresh copy of the /var/backups directory, but you also may want to take a snapshot of the server so you can quickly roll back.

Upgrading Sympl 10 to Sympl 11

This upgrade will move from PHP 7.3 to PHP 7.4, and replace Webalizer (which produces web traffic stats) with AWFfull.

If at any point you experience a problem with the below, you should restore

• Log into the server as root, or log in as sympl and use sudo su - to swap to the root user.
• Replace the current apt sources for Sympl to point to buster.

sed 's|buster|bullseye|g' /etc/apt/sources.list.d/sympl_buster.list > /etc/apt/sources.list.d/sympl_bullseye.list && rm /etc/apt/sources.list.d/sympl_buster.list

• Move the existing sources.list for Debian out of the way.

mv /etc/apt/sources.list /etc/apt/sources.list_buster_$( date +%s )

• Create a new sources list for bullseye.

echo "deb http://mirror.mythic-beasts.com/debian/ bullseye main
deb-src http://mirror.mythic-beasts.com/debian/ bullseye main

deb http://security.debian.org/debian-security bullseye-security main
deb-src http://security.debian.org/debian-security bullseye-security main

deb http://mirror.mythic-beasts.com/debian/ bullseye-updates main
deb-src http://mirror.mythic-beasts.com/debian/ bullseye-updates main" > /etc/apt/sources.list

• Check there will be enough disk space to download the updates.

apt update
apt -o APT::Get::Trivial-Only=true full-upgrade

• If there is a warning about not having enough disk space for the upgrade, then stop immediately, and either free up space or expand the disk before re-running the above command.
• Downtime will begin here, and you must complete the process in one go.
• Install the package updates that can be installed without installing anything new.

apt -y upgrade --without-new-pkgs

• When prompted, answer yes to restart services without asking.
• Upgrade all other packages.

apt -y full-upgrade

• When prompted, answer yes to upgrade the RoundCube database.
• When prompted, answer that you want to keep the existing modified RoundCube configuration file.
• Update the remaining depenencies.

apt -y install guile-2.2-libs --only-upgrade

• Remove the old packages which are no longer needed

apt -y autoremove

• Update the MariaDB service files to Sympl can interact with them.

systemctl disable mysql.service
systemctl enable mysql.service

• Reconfigure the Pure-FTPd authentication for Sympl.

rm /etc/pure-ftpd/auth/*
ln -s ../conf/ExtAuth /etc/pure-ftpd/auth/60Ext 

• Upgrade any web stats to the new file format

find /srv/*/config -maxdepth 1 -mindepth 1  -name 'stats' | sed 's|/config/stats||' | while read path ; do awffull_history_regen --dir "$path/public/htdocs/stats" > "$path/config/.webalizer.hist"; done

• Reboot the server to ensure all the updates are applied and you're running the new kernel.

shutdown -r now

• Reconnect to the server as root (or sympl, and then swap to root as before)
• Ensure Debian reports the correct version (Release 11)

lsb_release -a

• Make sure you're running the new kernel (5.x)

uname -r

• Check Sympl was upgraded okay (all versions should start '11.x'

dpkg -l 'sympl-*'

Finalising

You should now check all sites look as expected, and make any changes needed for the new PHP version. If you put any sites into maintenance mode, then once you're happy they're operating normally, you can put them back to normal.

Problems

While this has been tested multiple times, if you experience any problems or the upgrade fails, you may need to restore the server to it's previous state, in which case you can either restore a snapshot if you have one, or reinstall a fresh copy of the previous or new OS and restore the backups.

If you notice any non-critical issues, please either report them via [1] or the support forum along with as much information as possible.