Upgrading

When a new release is available, you will want to upgrade your own installation of PiAnoS. It is a very different operation from the installation, because you already have data and don’t want to lose it, at any rate. The good news is that it is also a much shorter operation because everything else is already configured.

Note

This is a generic procedure. If an update requires a different one, or needs specific tweaks, this will be explicitly mentioned on the Downloads page.

Preparing for upgrade

Performing an upgrade is a risky operation. It may fail, and render PiAnoS inaccessible and/or crash the database. Although 99% of the times everything goes well, you see where I am going:

Do a backup now ! This is explained in the Maintenance chapter. Don’t forget to backup your configuration file (backend/settings-local.php) as well.

Also, you should make sure nobody is using PiAnoS when you upgrade it. While it is not guaranteed that an update will make clients fail, it can happen. And anyway you don’t upgrade software that is being used.

Choosing an upgrade strategy

There are mainly 2 upgrade strategies. One is simple and consists in overwriting old files with the newer ones. The other consists in creating another “instance” of PiAnoS with the new version, then switching the link in Apache from the old to the new.

The second method allows easier rollbacks in case of failure and is good for production servers, while the first method is preferred on local systems (or non-risky situations). Note that if you have followed the Step-by-step installation on Debian Linux you are already using symlinks and should use this 2nd method.

Simple upgrade

  • Backup the database and the configuration file

  • Copy the entire directory (containing old files) to a temporary location

  • Download the new version of PiAnoS

  • Unpack the new files, overwriting current files

  • Remove the install/ directory (the installer should not be run again 1)

  • Open settings-local.php and update the version numbers of use_minified_pianos4 and use_minified_pianos4_backend. E.g. if upgrading from 4.0.0 to 4.1.0, change:

    Application::set('use_minified_pianos4', 'js/pianos-4.0.0.min.js');
Application::set('use_minified_pianos4_backend', 'js/pianos-backend-4.0.0.min.js');

    to

    Application::set('use_minified_pianos4', 'js/pianos-4.1.0.min.js');
Application::set('use_minified_pianos4_backend', 'js/pianos-backend-4.1.0.min.js');

  • Connect to PiAnoS. The Login page should show the updated version number

  • Log-in as administrator and check that things look normal (are your results still there? can you still review exercises? etc.)

If at any point things go wrong, you can restore both the files and the database so that you go back to the starting point. When you are certain that the upgrade was successful, you can get rid of the copy of the directory. Keep the config file and the database - these are the last known good backups of PiAnoS version <old>.

Production upgrade

  • Backup the database and the configuration file

  • Download and unpack the new version of PiAnoS

  • Install the files in a new directory under /var/www/pianos

  • Copy your settings-local.php to the backend directory (use -p to preserve permission mask and ownership)

  • Adjust the Javascript version numbers in this new file (see Simple upgrade above)

  • Remove the install/ directory

  • Change the symlink root/ symlink in /var/www/ to point to /var/www/pianos/pianos-4.2.1

  • Connect to PiAnoS. The Login page should show the updated version number

  • Log-in as administrator and check that things look normal (are your results still there? can you still review exercises? etc.)

For example, here is the transcript of an upgrade from 4.0.1 to 4.2.1:

$ whoami
bob
$ cd ~
$ wget -nc https://ips-labs.unil.ch/pianos/downloads/pianos-latest.tar.gz
$ tar -xvzf pianos-latest.tar.gz
$ cd /var/www/pianos/
$ sudo mv /home/bob/pianos-4.2.1/ .
$ ls -l
drwxr-xr-x 3 bob bob 4096 Nov  8 02:25 pianos-4.0.1
drwxr-xr-x 3 bob bob 4096 Dec 25 00:01 pianos-4.2.1
$ sudo cp -p pianos-4.0.1/backend/settings-local.php pianos-4.2.1/backend/
$ cd pianos-4.2.1/
$ sudo emacs backend/settings-local.php
    [ ... change version numbers of .js files ... ]
$ rm -rf install/
$ cd ../..
$ sudo rm root; ln -s pianos/pianos-4.2.1 root
$ ls -l
-rw-r--r-- 1 root root  177 Nov  8 00:58 index.html
drwxr-xr-x 3 root root 4096 Nov  8 02:25 pianos
lrwxrwxrwx 1 root root   25 Dec  8 00:04 root -> pianos/pianos-4.2.1/

As you can see, the old version has not been altered at all. We’ve simply added a new version, and switched the symlink. Rolling back to the previous version is even simpler: you only have to revert the symlink to pianos-4.0.1. Note however that this only works for releases that use the same database schema. For newer releases this may not be true (note that schema changes are indicated in the Downloads page). In this case, the only way to do a proper rollback is to both switch the symlink back to the older version AND to restore the backup you have made prior to the upgrade.

If you want to preserve the entire instance as it was prior to the upgrade, you can also duplicate the database. This can be done by creating an empty DB, and restoring your backup inside. You can take an even shorter route by issuing:

$ sudo su postgres
$ psql
$ CREATE DATABASE pianos421 WITH TEMPLATE pianos OWNER pianos;
$ \q

And then editing your settings-local.php, replacing Application::set('db_name', 'pianos'); by Application::set('db_name', 'pianos421'); 2. This way your instance prior to the upgrade is completely kept, and rolling back really boils down to changing the symlink back. New data will indeed not be part of this “frozen” instance, and the interest of doing a rollback late after upgrade is somewhat limited.

Footnotes

1

But you don’t really care, since you have a backup.

2

This may require you to adjust the connection settings in your pg_hba.conf file to allow the connection to the new pianos421 database.