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.

$ 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:

$ 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:

$ 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.

$ 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

$ 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:

$ 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:

$ 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.

$ 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:

$ 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.

#------------------------------------------------------------------------------
# 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.

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

Create the user and the database:

$ sudo su postgres
$ createuser pianos

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

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

$ 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:

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

And near the end (order is important, pianos must come before all):

[...]
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 Web Installer, 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

$ 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 Web Installer

Problems ?

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