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 :doc:`../download` 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 :doc:`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).


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
	* 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:
	
		.. code:: php
	
			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
	
		.. code:: php
	
			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
---------------------

.. note:: This part has not been written yet.