Step-by-step installation on Debian Linux
==============================================

.. note:: Tested on a fresh Debian 64 6.0.6 system. Recently (2014-01-06) re-tested against Debian 64 7.3.0, and slightly updated the procedure.
  
In this procedure we assume that PiAnoS will be served as document root (i.e. on ``/``). We'll use symlinks to manage the version changes. Running multiple instances and/or using different paths is left as an exercise.

Note that many commands are prefixed by ``sudo``, it simply mean they should be run as root [#f1]_

Pre-requisites
----------------

Install required software and modules. Using separate commands is not really required, but useful if you want to check what gets installed along the way.

.. code-block:: bash

	$ sudo aptitude install postgresql
	$ sudo aptitude install apache2
	$ sudo aptitude install libapache2-mod-php5 php5 php5-pgsql php5-gd php5-imagick

.. note:: Users of Ubuntu generally use ``apt-get`` instead of ``aptitude`` (the commands are still the same). Also, it might be that ``libapache2-mod-php5filter`` should be used instead of ``libapache2-mod-php5``. I have seen *one* situation where this was needed - was it a bug in the Ubuntu release I had at hand ?

		
Download
----------------

Download and unpack the release

.. code-block:: bash

	$ wget https://ips-labs.unil.ch/pianos/downloads/pianos-latest.tar.gz
	$ tar -xvzf pianos-latest.tar.gz
	$ ls
	pianos-4.0.1 pianos-latest.tar.gz
	

``pianos-latest.tar.gz`` is an alias for ``pianos-x.y.z.tar.gz``, so unpacking it reveals the actual version number. For the rest of this guide, we'll assume it's 4.0.1

Configure the web application
------------------------------

Create the web directory stub, place the file and the symlink

.. code-block:: bash

	$ cd /var/www
	$ sudo mkdir pianos
	$ sudo mv /home/bob/pianos-4.0.1/ pianos/
	$ sudo ln -s pianos/pianos-4.0.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   23 Nov  8 02:25 root -> pianos/pianos-4.0.1/
	
``index.html`` is Apache's default file, but it won't be used. Fire up your editor of choice [#f2]_ and create the following VirtualHost file

.. code-block:: bash

	$ sudo emacs /etc/apache2/sites-available/pianos

.. code-block:: xml

	<VirtualHost *:80>
		ServerAdmin bob@foo.net

		DocumentRoot /var/www/root/
		<Directory />
			#Options FollowSymLinks
			AllowOverride Limit
		</Directory>

		ErrorLog ${APACHE_LOG_DIR}/error.log

		# Possible values include: debug, info, notice, warn, error, crit,
		# alert, emerg.
		LogLevel warn

		CustomLog ${APACHE_LOG_DIR}/access.log combined
	</VirtualHost>

Activate it instead of Apache's default.

.. code-block:: bash

	$ sudo a2dissite default
	$ sudo a2ensite pianos
	$ sudo /etc/init.d/apache2 reload

[Optionnally] Create the local settings file with ownership by www-data to ease the forecoming web installation

.. code-block:: bash

	$ cd /var/www/pianos/pianos-4.0.1/backend/
	$ sudo touch settings-local.php
	$ sudo chown www-data settings-local.php
	$ sudo chmod 600 settings-local.php
	

.. _tbs-debian-pg-setting:
	
Configure the database
-------------------------

PiAnoS requires the custom variable class 'unil' to be defined. This can be done in ``postgres.conf``. On our simple system it is
	
.. code-block:: bash

	$ sudo emacs /etc/postgresql/8.4/main/postgresql.conf
	
Uncomment and change the very last line to:

.. code-block:: python

	#------------------------------------------------------------------------------
	# CUSTOMIZED OPTIONS
	#------------------------------------------------------------------------------

	custom_variable_classes = 'unil'           # list of custom variable class names

If you use PostgreSQL 9.x, you have an additionnal setting to adapt: `standard_conforming_strings`, which must be set to 'off' for PiAnoS to work properly. The default is 'off' on versions prior to 9.x, and 'on' from there on, so 8.x users may want to check this value as well.

.. code-block:: python

	#------------------------------------------------------------------------------
	# VERSION/PLATFORM COMPATIBILITY
	#------------------------------------------------------------------------------

	[...]
	standard_conforming_strings = off
	[...]


Create the user and the database:

.. code-block:: bash

	$ sudo su postgres
	$ createuser pianos
	Shall the new role be a superuser? (y/n) n
	Shall the new role be allowed to create databases? (y/n) n
	Shall the new role be allowed to create more new roles? (y/n) n
	$ createdb --owner=pianos --encoding=utf-8 pianos
	$ createlang plpgsql -d pianos
	$ exit

.. note:: If at this point, you see the message ``createlang: language "plpgsql" is already installed in database "pianos"``, it is not an error and you may proceed safely.
	
Allow the web application to connect to the database

.. code-block:: bash

	$ sudo emacs /etc/postgresql/8.4/main/pg_hba.conf
	
And near the end (order is important, ``pianos`` must come before ``all``):

.. code-block:: python

	[...]
	# IPv4 local connections:
	host pianos pianos 127.0.0.1/32 trust # <-- Add this line (and remove this comment)
	host    all         all         127.0.0.1/32          md5
	# IPv6 local connections:
	host    all         all         ::1/128               md5

.. note:: During the :doc:`webinstall`, you may get the error ``Unable to connect to PostgreSQL server: fe_sendauth: no password supplied``. This may be because your system uses IPv6, and therefore bypasses the rule we've created. If this happens, you'll want to either set the PostgreSQL hostname to ``127.0.0.1`` (instead of ``localhost``) to force use of IPv4, or write ``host pianos pianos ::1/128 trust`` in your ``pg_hba.conf`` (just below the comment #IPv6 local connections)
	
Now restart the server to apply the changes

.. code-block:: bash

	$ sudo /etc/init.d/postgresql restart

Launch the installer
---------------------

Using a web browser, open the URL ``http://localhost/install/`` (replacing ``localhost`` by the IP address or the hostname of your server, if not running on your local computer).

Follow the procedure detailed in :doc:`webinstall`

Problems ?
---------------------

Some known problems are listed in the :doc:`troubleshooting` section. If you have a problem, make sure you read this chapter before attempting anything else.


.. rubric:: Footnotes

.. [#f1] I prefer switching to root via ``su`` but this is personal taste. And default Debian system do not have ``sudo`` installed, actually. 
.. [#f2] Of course ``Emacs``, you aren't ``vi``, are you ? [#f3]_
.. [#f3] If you have no favourite, it is now time to choose your side. `This is the ultimate reference <http://c2.com/cgi/wiki?EmacsVsVi>`_ on the topic (as well as on many others), and there is `an infinite amount of documentation <http://www.google.com/search?q=emacs+vi+war>`_ on this essential subject.