diff --git a/doc/source/admin/install/debian.rst b/doc/source/admin/install/debian.rst index f3d0f39292bb1eabab42506e63e1bfca08f5f9e4..de95a5ee62661f25cdbe878ab6d7cb2091d35247 100644 --- a/doc/source/admin/install/debian.rst +++ b/doc/source/admin/install/debian.rst @@ -1,121 +1,105 @@ 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. +.. note:: Tested on a fresh Debian 9.4 system (64-bit). 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 aptitude install postgresql - $ sudo aptitude install apache2 - $ sudo aptitude install libapache2-mod-php5 php5 php5-pgsql php5-gd php5-imagick + $ sudo apt install postgresql + $ sudo apt install apache2 libapache2-mod-php php php-mbstring php-pgsql php-gd php-imagick -.. note:: Users of Ubuntu generally use ``apt-get`` (or for more modern users ``apt``) 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 +Download and unpack the latest release from the official Git repo `here http://ips-labs.unil.ch:1337/PiAnoS/src/tags`: .. code-block:: bash - $ wget https://ips-labs.unil.ch/pianos/downloads/pianos-latest.tar.gz - $ tar -xvzf pianos-latest.tar.gz + $ cd /tmp + $ wget http://ips-labs.unil.ch:1337/PiAnoS/src/-/archive/latest/src-latest.tar.gz + $ tar -xvzf src-latest.tar.gz $ ls - pianos-4.0.1 pianos-latest.tar.gz - + 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 -``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 + $ sudo apt install git + $ cd /tmp + $ git clone http://ips-labs.unil.ch:1337/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 stub, place the file and the symlink +Create the web directory, copy the files OR create a symlink to the installation folder. .. 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 and create the following VirtualHost file + $ 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 - $ sudo emacs /etc/apache2/sites-available/pianos + $ 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 -.. code-block:: xml +Configure the libraries +----------------------- - - ServerAdmin bob@foo.net +PiAnoS need multuples libraries to run. The different libraries can be installed in the ``backend`` folder, or in the php_shared folder (prefered method). - DocumentRoot /var/www/root/ - - #Options FollowSymLinks - AllowOverride Limit - +To find the location of the php_shared folder, type: - ErrorLog ${APACHE_LOG_DIR}/error.log +.. code-block:: bash - # Possible values include: debug, info, notice, warn, error, crit, - # alert, emerg. - LogLevel warn + $ php -i | grep include_path + include_path => .:/usr/share/php => .:/usr/share/php - CustomLog ${APACHE_LOG_DIR}/access.log combined - +In this case, the libraires will be installed in the ``/usr/share/php`` folder. -Activate it instead of Apache's default. +This installation can be done by cloning the Git repo OR downloading the released archive from the Git repo: .. code-block:: bash - $ sudo a2dissite default - $ sudo a2ensite pianos - $ sudo /etc/init.d/apache2 reload + $ cd /usr/share/php + $ sudo git clone http://ips-labs.unil.ch:1337/PiAnoS/php_classes.git . -[Optionnally] Create the local settings file with ownership by www-data to ease the forecoming web installation +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/pianos/pianos-4.0.1/backend/ - $ sudo touch settings-local.php - $ sudo chown www-data settings-local.php - $ sudo chmod 600 settings-local.php - + $ cd /var/www/html/ + $ sudo mkdir cdn + $ cd cdn + $ sudo git clone http://ips-labs.unil.ch:1337/PiAnoS/cdn.git . -.. _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 +The configuration of the posgreql database is done in the ``postgres.conf`` file: .. 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 + $ sudo nano /etc/postgresql/9.6/main/postgresql.conf 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. @@ -129,6 +113,13 @@ If you use PostgreSQL 9.x, you have an additionnal setting to adapt: `standard_c 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: @@ -136,9 +127,15 @@ Create the user and the database: $ 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 + +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 @@ -149,21 +146,20 @@ Allow the web application to connect to the database .. code-block:: bash - $ sudo emacs /etc/postgresql/8.4/main/pg_hba.conf + $ 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 [...] - # 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 + 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 + 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 diff --git a/doc/source/admin/install/docker.rst b/doc/source/admin/install/docker.rst index 286c55ffffd7214f5dad63c0ba73993f1a6a1c1f..6eb54640764ca5881808fd536ec6907f7ab120e8 100644 --- a/doc/source/admin/install/docker.rst +++ b/doc/source/admin/install/docker.rst @@ -1,8 +1,6 @@ Step-by-step installation on Docker =================================== -This installation method being very new to PiAnoS, the git repo is EXPERIMENTAL. Force-push should not be done in this repo, however, before pulling the new version over an already installed version of PiAnoS, please make a backup of the PostgreSQL folder!! - Install Docker -------------- @@ -17,10 +15,10 @@ In a second step, you have to install docker-compose with the following commands .. code-block:: bash - $ sudo curl -L https://github.com/docker/compose/releases/download/1.21.0/docker-compose-$(uname -s)-$(uname -m) -o /usr/local/bin/docker-compose + $ sudo curl -L https://github.com/docker/compose/releases/download/1.21.2/docker-compose-$(uname -s)-$(uname -m) -o /usr/local/bin/docker-compose $ sudo chmod +x /usr/local/bin/docker-compose -The latest version of docker-compose should be downloaded (1.21.0 at this moment as mentionned in the download URL). See the |dockerinstalldoc| and |dockercomposedoc| for more details. +The latest version of docker-compose should be downloaded (1.21.2 at this moment as mentionned in the download URL). See the |dockerinstalldoc| and |dockercomposedoc| for more details. Download the PiAnoS image ------------------------- diff --git a/doc/source/admin/install/troubleshooting.rst b/doc/source/admin/install/troubleshooting.rst index a12a6f96ddb9085699c9b6deb93cea78b15ad44a..915fd005ad13536f2744c59bf8101aeed16b47bd 100644 --- a/doc/source/admin/install/troubleshooting.rst +++ b/doc/source/admin/install/troubleshooting.rst @@ -3,14 +3,6 @@ Troubleshooting This chapter is a collection of known problems that can arise when installing PiAnoS. If a problem you have solved is not described here, feel free to drop me a line with the platform, problem, and steps to resolve. -All platforms ------------------------------- - - * FATAL: unknown configuration parameter "unil.user" - (in French: ERREUR: paramètre de configuration « unil.user » non reconnu) - - This happens when you have forgotten to set the ``custom_variable_classes`` option in ``postgresql.conf``. The detailed procedures explain how to do this on :ref:`Linux ` and on :ref:`Windows `. - Linux ------------------------------ @@ -21,4 +13,3 @@ Linux Windows ------------------------------ - diff --git a/doc/source/admin/install/webinstall.rst b/doc/source/admin/install/webinstall.rst index f906feba8260a41dbd556168fe257bf9dd1299b2..0239c46a36f5e0e926d5b911b7ebd1d533efe424 100644 --- a/doc/source/admin/install/webinstall.rst +++ b/doc/source/admin/install/webinstall.rst @@ -1,43 +1,36 @@ Web Installer -================================== +============= -Once installed, PiAnoS has a web interface dedicated to creating the database schema (the actual tables) and the configuration file. It is a simple (read: not so smart) wizard whose steps are detailed below. +Once installed, PiAnoS has a web interface dedicated to creating the database schema (the actual tables) and the configuration file. It is a simple wizard whose steps are detailed below. Even though the wizard can be restarted (by restarting the browser or click the 'reset' link) the creation of the schema is an irreversible operation. If you need to restart completely from scratch, you need to drop and re-create the database. -Introduction ------------------ - -Read it, don't read it. It doesn't really matter. - Config check ------------------ +------------ The configuration check is only informative for the moment. But clearly, seing alerts here and errors later should ring a bell. -.. _db-setup: - Database setup ------------------ +-------------- You need to enter all of hostname, port, database and username. The password is optional, depending on how ``pg_hba.conf`` allows connections to the database. If you put a password here, you probably want to ``chmod 600`` and ``chown www-data`` your ``local-settings.php`` file so that it is only readable by the web server. -The Test button allows you to check the connection (through an AJAX call, faster than clicking Next). +The Test button allows you to check the connection. .. note:: If you get an error message like ``Unable to connect to PostgreSQL server: fe_sendauth: no password supplied``, please see the relevant note in :doc:`debian` regarding ``pg_hba.conf`` and IPv6. Database initialization --------------------------- +----------------------- There is only one button here, so you may want to click on it. As said above, once the schema is created you can't roll back the operation. You will simply see a message saying the database is ready. -.. note:: If you see an error (red frame), and the message contains the words "language plpgsql does not exist", your database is missing a small adjustment. You need to run the `createlang` command. On Linux, this is ``createlang plpgsql -d ``, on Windows most probably ``C:\Program Files (x86)\PostgreSQL\8.4\bin\createlang.exe plpgsql -d ``, where ```` is the name of your database. Alternatively, you can log into the database using ``psql -h -U pianos `` and issue the SQL statement ``CREATE LANGUAGE plpgsql;``. +.. note:: If you see an error (red frame), and the message contains the words "language plpgsql does not exist", your database is missing a small adjustment. You need to run the `createlang` command. On Linux, this is ``createlang plpgsql -d ``, on Windows most probably ``C:\Program Files (x86)\PostgreSQL\9.6\bin\createlang.exe plpgsql -d ``, where ```` is the name of your database. Alternatively, you can log into the database using ``psql -h -U pianos `` and issue the SQL statement ``CREATE LANGUAGE plpgsql;``. Advanced settings & customization ------------------------------------ +--------------------------------- Proposed settings should be fine - just make sure the Path is correct. It should match the absolute path to PiAnoS on the server. If PiAnoS is the only (i.e. it is the document root) then the Path must be ``/``. @@ -45,7 +38,7 @@ If users cannot log-in (keep seeing the login page even after correct authentica Configuration file --------------------- +------------------ The PiAnoS configuration is ``backend/local-settings.php``. It is a mean to override the default configuration options. The wizard only allows to modify a couple values. See :doc:`../configuration` for more information. @@ -55,12 +48,11 @@ Here you will be able to : Finalization --------------------- +------------ This screen is mostly informative. You will be able to log-in using the ``admin`` account as soon as you have deleted the ``install/`` directory. 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. - diff --git a/doc/source/admin/install/win7.rst b/doc/source/admin/install/win7.rst index 89825da3ccb77559af7f139b14535953c25859cf..ecfc7b4a3d97e7cd3e7ad0358123d02f577d9691 100644 --- a/doc/source/admin/install/win7.rst +++ b/doc/source/admin/install/win7.rst @@ -1,13 +1,13 @@ -Step-by-step installation on Windows 7 -======================================== +Step-by-step installation on Windows +==================================== -This chapter covers the installation on a Windows 7 64-bit system. The process is in essence the same as in :doc:`debian` but must be translated to the Windows world. PostgreSQL, Apache and PHP must be downloaded and installed separately. The location of their configuration files, how they are started/stopped is also vastly different. +This chapter covers the installation on a Windows 64-bit system. The process is in essence the same as in :doc:`debian` but must be translated to the Windows world. PostgreSQL, Apache and PHP must be downloaded and installed separately. The location of their configuration files, how they are started/stopped is also vastly different. -In this procedure we assume that PiAnoS will be served as document root (i.e. on ``/``). Running multiple instances and/or using different paths is left as an exercise. +The installation can be done on a Windows Server or Windows 7/8/10 installation. -.. note:: The procedure should be very similar for Windows Vista and 8 (if not identical). Things are slightly different for Windows XP and/or on a 32-bit system but you should be able to figure out how to cope with the variations. +In this procedure we assume that PiAnoS will be served as document root (i.e. on ``/``). Running multiple instances and/or using different paths is left as an exercise. -.. note:: This installation method is not recommanded (because of Windows...). Use some opensource OS for philosophical purpouse (even if I'am coding the dev version of PiAnoS on a Windows 10 machine ...). +.. note:: This installation method is not recommanded. Use some OpenSource OS for philosophical purpouse. Downloading applications ------------------------------ @@ -15,24 +15,11 @@ Downloading applications Get the 32-bit [#f1]_ installers for the dependencies. Unless you know what you are doing, download the latest version of the branch specified by the compatibility chart in :doc:`requirements`. - PostgreSQL: http://www.postgresql.org/download/windows/ - - Following the "Download" link will redirect you to EntrepriseDB's installer page (which is fine since EnterpriseDB is a key supporter of PostgreSQL) where you have to scroll down a bit to find a download for the 8.4 branch. - - Apache: http://httpd.apache.org/download.cgi - - The Apache team does not make it easy for Windows users to locate the right file to download. From the provided link, scroll down to the latest version (2.4.4) and choose "Other files". From there, browse to "binaries", then "win32". This is where the latest builds for Windows live. Now choose the latest ``.msi`` file (2.2.22 in our case, go figure) for x86 processors, including openssl. The actual link is (2013.05.08) http://mirror.switch.ch/mirror/apache/dist//httpd/binaries/win32/httpd-2.2.22-win32-x86-openssl-0.9.8t.msi (note that this is the Swiss mirror, you'll probably end up using another one closer to you if you follow the steps described here). - - - PHP: http://windows.php.net/download. - - From there, scroll down to the latest version (5.4.14 at time of writing) and choose the thread-safe version, compiled by VC9 for x86 processors. Download the ``.zip`` archive - the installer is a wreck anyway, so we're better off installing manually. - - - Notepad++: http://notepad-plus-plus.org - - This has nothing to do with PiAnoS per se, but we'll need to edit some files. The default text editor in Windows is a pain, while Notepad++ is both free and incredibly good. Later, instead of double-clicking ``.ini``, ``.conf`` or ``.txt`` files (and 50% of the times be asked what program to use, and the remaining 50% see Windows use the wrong program), just right-click them and choose "Open with Notepad++". Sorry for the proselytism, but this one is a real must. - - + - PHP: http://windows.php.net/download + Install the applications ------------------------------- +------------------------ .. note:: this will install services on your local system. These will load at startup and may eat memory and CPU time. If this is not what you want, turn them to *manual* mode, and start them only when needed. You can do so by going to the Services Management console (after Apache and PostgreSQL are installed, of course). @@ -46,8 +33,7 @@ Install the applications - `[Note: Not sure if and when this question is asked by the installer]`. There may be a checkbox named "install PL/pgSQL in template1 database" (or something similar). If you see it, make sure it is checked. - Start the installation - After the installation is finished, uncheck the "Execute Stack Builder" box. (Stack Builder is a very handy program to install third-party tools for e.g. live replication, spatial databases, etc. We don't need any of them now, but you may launch it at any time later) - - + **Apache** - Launch the installer @@ -78,7 +64,7 @@ PHP is actually a module for Apache and we need to make them live together. LoadModule php5_module "C:/Program Files (x86)/PHP/php5apache2_2_filter.dll" AddType application/x-httpd-php .php - Note the forward slashes in the paths - this is not a typo, Apache requires forward slashes. + Note the forward slashes in the paths - this is not a typo, Apache requires forward slashes. The version of the php module has to be patch. - Somewhere in the middle of this file, there is a section like the following (search for the "DocumentRoot" string using Ctrl+F) @@ -160,23 +146,9 @@ If some modules are missing, you need to investigate why. The best method is to Configure the database ------------------------- -PiAnoS requires the custom variable class 'unil' to be defined. This can be done in ``C:\Program Files (x86)\PostgreSQL\8.4\data\postgresql.conf``. Open this file in Notepad++, and scroll down to the end of the file. - -Uncomment and change the very last line to: - -.. code-block:: python - - #------------------------------------------------------------------------------ - # CUSTOMIZED OPTIONS - #------------------------------------------------------------------------------ - - custom_variable_classes = 'unil' # list of custom variable class names - -Now restart the server to apply the changes, by running Start Menu / PostgreSQL 8.4 / Restart Server in Administrator mode. This can be done by right-clicking the item, and choosing "Run as administrator". - -While we could use command-line utilities to create the database, we'll use the nice ``pgAdmin III`` program. This is more Window-ish and you will have no excuses when asked how to backup the database (answer: start pgAdmin, right-click db, click backup). +While we could use command-line utilities to create the database, we'll use the nice ``pgAdmin 4`` program. This is more Window-ish and you will have no excuses when asked how to backup the database (answer: start pgAdmin, right-click db, click backup). - - Start pgAdmin III (from your start menu) + - Start pgAdmin 4 (from your start menu) - In the Object Browser, double-click "PostgreSQL 8.4 (localhost:5432)" - Enter the password you have defined earlier - In the tree that has expanded, right-click "Login Roles" and choose "New Login Role ..."