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

.. note:: Tested on a fresh Debian 10 system (64-bit), but should work on any modern version of Debian. The Virtual Machine has been configured on an English installation.
  
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.

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 apt install postgresql
	$ sudo apt install apache2 libapache2-mod-php php php-mbstring php-pgsql php-gd php-imagick

Download
--------

Download and unpack the latest release from the official Git repo `here https://esc-md-git.unil.ch/PiAnoS/src/tags`:

.. code-block:: bash

	$ cd /tmp
	$ wget https://esc-md-git.unil.ch/PiAnoS/src/-/archive/latest/src-latest.tar.gz
	$ tar -xvzf src-latest.tar.gz
	$ ls
	src-latest  src-latest.tar.gz

The installation can of course be installed by cloning the Git repo directly, allowing to upgrade easely the code base:

.. code-block:: bash

	$ sudo apt install git
	$ cd /tmp
	$ git clone https://esc-md-git.unil.ch/PiAnoS/src.git src-latest

The Git repo store all versions of PiAnoS. The master branch is updated lowly. The develop branch is used to release as soon as possible the new.

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

Create the web directory, copy the files OR create a symlink to the installation folder.

.. code-block:: bash

	$ cd /var/www/html
	$ sudo rm index.html
	$ sudo cp -r /tmp/src-latest/* /var/www/html

``index.html`` is Apache's default file, but it won't be used, hence beeing removed.

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

.. code-block:: bash

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

Configure the libraries
-----------------------

PiAnoS need multuples libraries to run. The different libraries need to be installed in the php_shared folder.

To find the location of the php_shared folder, type:

.. code-block:: bash

	$ php -i | grep include_path
	include_path => .:/usr/share/php => .:/usr/share/php

In this case, the libraires will be installed in the ``/usr/share/php`` folder.
This is the standared location on Debian (probably also for all Gnu/Linux based machines).

This installation can be done by cloning the Git repo OR downloading the released archive from the Git repo:

.. code-block:: bash

	$ cd /usr/share/php
	$ sudo git clone https://esc-md-git.unil.ch/PiAnoS/php_classes.git .

.. note:: The ``unil`` folder has to be at the "root" of the shared folder!

PiAnoS need also some third-party libraries, like jquery, toast, TPSjs,... The installation is done by default in the ``/cdn``, but can be changed in the ``settings-local.php`` file.

.. code-block:: bash

	$ cd /var/www/html/
	$ sudo mkdir cdn
	$ cd cdn
	$ sudo git clone https://esc-md-git.unil.ch/PiAnoS/cdn.git .

Configure the database
----------------------

The configuration of the posgreql database is done in the ``postgres.conf`` file:
	
.. code-block:: bash

	$ sudo nano /etc/postgresql/9.6/main/postgresql.conf

If you use PostgreSQL 9.x or later, 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
	[...]

If the database need to be accessible from outside the local machine, the listen address also need to be updated.

.. code-block:: python

	[...]
	listen_addresses = '*'	
	[...]

Create the user and the database:

.. code-block:: bash

	$ sudo su postgres
	$ createuser pianos

To change the password of the postgresql database, the following command have to be used:

.. code-block:: bash

	$ psql -c "ALTER USER pianos WITH PASSWORD 'pianos';"

.. code-block:: bash

	$ 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.
	
To allow the connection of the pianos user without password from ``localhost``, change the configuration in the ``pg_hba.conf`` file as follow:

.. code-block:: bash

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

.. code-block:: python

	[...]
	host	pianos		pianos		127.0.0.1/32		trust
	
	host    all         all         127.0.0.1/32        md5
	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.
