View source for Upgrading Sympl

Upgrading Sympl versions is a little more complicated than a standard [[Debian]] upgrade but has been tested thoroughly with servers using the [https://www.mythic-beasts.com Mythic Beasts] Debian/Sympl images.

Unfortunately this guide doesn't cover other hosting providers, as there tend to be small differences in packages and configurations between them and you may encounter other prompts during the upgrade.

Note that this is different the the typical "update" via running <code>sympl update</code>. That 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 (e.g. 11 to 12).

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.

==Assumptions==
This guide makes the following assumptions:

*You're familiar with SSH and running commands as the <code>root</code> 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 wish 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 separate from the existing server, that they contain all the relevant information and that 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 <code>/var/backups</code> directory.
*Apply any pending upgrades for the current setup:
<pre>
sudo apt -y update
sudo apt -y upgrade
sudo apt -y dist-upgrade
sudo sympl update
</pre>

*Reboot the server to ensure it is working normally and you have a stable platform for the update:
<pre>shutdown -r now</pre>

*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 <code>sudo backup2l -b</code> to make a new backup then ensure you have a fresh copy of the <code>/var/backups</code> directory. 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]] - the format of the web traffic statistics generated are incompatible, so stats will be generated without any history.

If at any point you experience a problem with the below you should restore from the most recent backup. 

*Log into the server as <code>root</code>, or log in as <code>sympl</code> and use <code>sudo su -</code> to swap to the <code>root</code> user.
*Replace the current apt sources for Sympl to point to buster:
<pre>
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
</pre>

*Move the existing sources.list for Debian out of the way:
<pre>
mv /etc/apt/sources.list /etc/apt/sources.list_buster_$( date +%s )
</pre>

*Create a new sources list for bullseye:
<pre>
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
</pre>

*Check there will be enough disk space to download the updates:
<pre>
apt update
apt -o APT::Get::Trivial-Only=true full-upgrade
</pre>

*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:
<pre>
apt -y upgrade --without-new-pkgs
</pre>

*When prompted, answer '''yes''' to restart services without asking.
*Upgrade all other packages:
<pre>
apt -y full-upgrade
</pre>

*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 dependencies:
<pre>
apt -y install guile-2.2-libs --only-upgrade
</pre>

*Remove the old packages which are no longer needed:
<pre>
apt -y autoremove
</pre>

*Update the MariaDB service files to Sympl can interact with them:
<pre>
systemctl disable mysql.service
systemctl enable mysql.service
</pre>

*Reconfigure the Pure-FTPd authentication for Sympl:
<pre>
rm /etc/pure-ftpd/auth/*
ln -s ../conf/ExtAuth /etc/pure-ftpd/auth/60Ext 
</pre>

*Move the old web stats out of the way so new ones can be generated:
<pre>
find /srv/*/config -maxdepth 1 -mindepth 1  -name 'stats' | sed 's|/config/stats||' | while read dir; do if [ -d "$dir/public/htdocs/stats" ]; then mv -v "$dir/public/htdocs/stats" "$dir/public/stats_sympl10" ; mkdir "$dir/public/htdocs/stats" ; fi ; done
</pre>

*Reboot the server to ensure all the updates are applied and you're running the new kernel:
<pre>
shutdown -r now
</pre>

*Reconnect to the server as <code>root</code> (or <code>sympl</code>, 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-*'

===Sympl 11 to Sympl 12===

This upgrade will move from PHP 7.4 to PHP 8.2 by default, but with a great deal of new PHP configuration options, allowing you to run a site under various PHP versions.

If at any point you experience a problem with the below you should restore from the most recent backup. 

*Log into the server as <code>root</code>, or log in as <code>sympl</code> and use <code>sudo su -</code> to swap to the <code>root</code> user.

* Disable the old Sympl repo
<pre>sed -i 's|^deb.*|#&|' /etc/apt/sources.list.d/sympl_bullseye.list
mv /etc/apt/sources.list.d/sympl_bullseye.list /etc/apt/sources.list.d/disabled-$( date +%s )_sympl_bullseye.list
</pre>

* Disable other old Repos for Debian Bullseye
<pre>
sed -i 's|^deb http://packages.mythic-beasts.com/mythic/.*|#&|' /etc/apt/sources.list.d/*.list
sed -i 's|^deb .* bullseye .*|#&|' /etc/apt/sources.list.d/*.list
</pre>

* Add the new Apt Repository for Sympl 12 and add the key.
<pre>
echo "deb http://packages.mythic-beasts.com/mythic/ bookworm main" > /etc/apt/sources.list.d/sympl_bookworm.list
wget -q https://mirror.mythic-beasts.com/mythic/support@mythic-beasts.com.gpg.key -O /etc/apt/trusted.gpg.d/support@mythic-beasts.com.asc
</pre>

*Move the existing sources.list for Debian out of the way:
<pre>
mv /etc/apt/sources.list /etc/apt/sources.list_bullseye_$( date +%s )
</pre>

*Create a new sources list for bullseye:
<pre>
echo "deb http://mirror.mythic-beasts.com/debian/ bookworm main
deb-src http://mirror.mythic-beasts.com/debian/ bookworm main

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

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

*Set some options for updates:
<pre>
export DEBIAN_FRONTEND=noninteractive 
export UCF_FORCE_CONFFNEW=YES
</pre>

*Check there will be enough disk space to download the updates:
<pre>
apt update
apt -qq -o APT::Get::Trivial-Only=true full-upgrade 2>&1 | tail -n 3 | grep -v 'Trivial Only'
</pre>

*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 now complete the remainder of this process in one go.
*Install the package updates that can be installed without installing anything new:
<pre>
apt -y upgrade --without-new-pkgs
</pre>

*If prompted, answer '''yes''' to restart services without asking.
*Disable the old PHP Apache Module
<pre>a2dismod php7.4</pre>
*Upgrade all other packages:
<pre>
apt -o Dpkg::Options::="--force-confnew" -y full-upgrade
</pre>

*Remove the old packages which are no longer needed:
<pre>
apt -y purge cracklib-runtime
apt -y install cracklib-runtime
apt -y autoremove
</pre>

* Fix webmail hostname prompt:

 sudo sed -i "s|'default_host'|'imap_host'|g" /var/lib/roundcube/config/config.sympl.inc.php
*Reboot the server to ensure all the updates are applied and you're running the new kernel:
<pre>
shutdown -r now
</pre>

*Reconnect to the server as <code>root</code> (or <code>sympl</code>, and then swap to root as before)
*Ensure Debian reports the correct version (Release 12):

 lsb_release -a

*Make sure you're running the new kernel (6.x):

 uname -r

*Check Sympl was upgraded okay (all versions should start '12.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. 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 [https://bugs.sympl.io the issue tracker] or the [https://forum.sympl.io/c/support/ support forum] along with as much information as possible.

[[Category:How To]]
[[Category:Upgrading]]