Step-by-step installation on Windows
====================================

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.

The installation can be done on a Windows Server or Windows 7/8/10 installation.

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. Use some OpenSource OS for philosophical purpouse. Moreover, the installation on a Linux box is way easier. The recommended method is to install the "Docker for windows" (via the docker toolkit) or, the better way, install a very small Debian (or any Linux) virtual machine (with VMware Player or Virtualbox for example), and make the installation as describe for the Linux OS (the "Docker" way or the "monolithique" way).

Downloading applications
------------------------------

Get the latest version of:
	
	- PostgreSQL: http://www.postgresql.org/download/windows/
	- Apache: http://httpd.apache.org/download.cgi
	- PHP: http://windows.php.net/download

.. note:: It is possible to use for example WAMP, but since the MySQL server is not used in this case, a simple installation of Apache2 alone is more efficient.

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

**PostgreSQL**

	- Launch the installer
	- Accept the default installation and data folders
	- Choose a password for the database administrator, ``postgres``. This user will exist both a Windows account and as a role in the database cluster. If your system is somewhat public, or even worse, facing the Internet, please choose a strong password. In all cases, **make sure you remember it**.
	- Accept the default port (5432)
	- Accept the default locale, or set it to the country you live in explicitly (e.g. "English, United States"). This will mostly affect how messages and dates are printed. Leave the checkbox below checked.
	- `[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
	- Use your ordinary process to go through the license steps
	- In the "Server Information" panel, you may accept the defaults - these will not prevent Apache from working if they are not set correctly. If you have sensible information to enter at this point, please do so.
	- In the same pane, make sure "for All users, on port 80, as a service" is checked
	- Choose a "Typical" setup, and accept the default installation path
	- Start the installation
	- When the installation is finished, point your web browser to the URL ``http://localhost``. You should see the famous **It works!** message.

**PHP, Part 1**

PHP is actually a module for Apache and we need to make them live together.

	- Create a folder named ``PHP`` in your ``Program Files (x86)``, i.e. ``C:\Program Files (x86)\PHP``.
	- Extract the content of the archive inside this folder
	- There is a file named ``C:\Program Files (x86)\PHP\install.txt``. You may want to read it, and follow the "Manual installation" procedure, instead of reading this - your choice.
	- Copy ``C:\Program Files (x86)\PHP\php.ini-production`` to ``C:\Program Files (x86)\PHP\php.ini``
	- To easily modify the configuration file, we need to set the right permission [#f2]_. Right-click ``C:\Program Files (x86)\PHP\php.ini``, select "Properties". Go to the "Security" tab, click "Modify", select "Users" in the list and click "Full control" in the permissions . Validate with OK.
	- Use the same trick to allow the modification of Apache configuration file, named ``C:\Program Files (x86)\Apache Software Foundation\Apache2.2\conf\httpd.conf`` [#f2]_
	- Create a directory named ``www`` e.g. at the root of your drive (``C:\www``). This is where we are going to store our web files.
	- Open ``C:\Program Files (x86)\Apache Software Foundation\Apache2.2\conf\httpd.conf``, go to the end of the file and append:
	
	.. code-block:: xml

		LoadFile "C:/Program Files (x86)/PHP/libpq.dll"
		PHPIniDir "C:/Program Files (x86)/PHP/"
		LoadModule php5_module "C:/Program Files (x86)/PHP/php5apache2_2_filter.dll"
		AddType application/x-httpd-php .php
	
	Adapte the installation of the PHP module if using the PHP7 version.
	
	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)
	
	.. code-block:: xml
	
		# [ ... ]
		# DocumentRoot: The directory out of which you will serve your
		# documents. By default, all requests are taken from this directory, but
		# symbolic links and aliases may be used to point to other locations.
		#
		DocumentRoot "C:/Program Files (x86)/Apache Software Foundation/Apache2.2/htdocs"

		# [ ... ]
		#
		# This should be changed to whatever you set DocumentRoot to.
		#
		<Directory "C:/Program Files (x86)/Apache Software Foundation/Apache2.2/htdocs">	
			# [ ... ]

	Replace references to ``htdocs`` to ``www``, so the block now looks like:
	
	.. code-block:: xml
	
		# [ ... ]
		DocumentRoot "C:/www"
		# [ ... ]
		<Directory "C:/www">	
			# [ ... ]
	
	Finally, for convenience, set the DirectoryIndex to show index.php:
	
	.. code-block:: xml

		# DirectoryIndex: sets the file that Apache will serve if a directory
		# is requested.
		<IfModule dir_module>
			DirectoryIndex index.html index.php
		</IfModule>
	
	- Restart the Apache server (use either the Apache Monitor that sits in your notification area, or the program in Start Menu / Apache HTTP Server 2.2 / Control Apache Server / Restart)
	- Using explorer (the windows shell, not Internet Explorer), go to ``C:\www``. Create a file named ``index.php`` and put the following content in it:
	
	.. code-block:: php
	
		<?php
		phpinfo();
		
	- Save the file, and point your web browser to ``http://localhost/index.php``. You should now see the `PHP Information page <http://www.google.com/images?q=phpinfo>`_.
	
**PHP, Part 2**	

.. note:: If you have not seen the PHP Information page, you cannot proceed further. You probably have missed something somewhere, so please double-check everything. I cannot provide troubleshooting instructions here because the depdendency on your particular setup is too strong.

Now that PHP is active, we need to activate some required modules for PiAnoS (e.g. PostgreSQL, imaging libraries, etc.). Even if you used the automated installer (because it was available to you, while it was not when this procedure was written), you need to perform these steps.

You need to perform the following list of changes in your ``C:\Program Files (x86)\PHP\php.ini`` file. Use Ctrl+F to find the key and set the value appropriately. If the line is commented (i.e. begins with a semicolon ``;``) you should first uncomment it and then set the value. These settings are actually scattered all around the ``php.ini`` file.

.. code-block:: ini

	post_max_size = 32M
	upload_max_filesize = 8M
	extension_dir = "C:\Program Files (x86)\PHP\ext"
	extension=php_curl.dll
	extension=php_fileinfo.dll
	extension=php_gd2.dll
	extension=php_gettext.dll	
	extension=php_mbstring.dll
	extension=php_exif.dll	
	extension=php_pgsql.dll

You can now restart the Apache server, and refresh the PHP Information page. If everything is correct, you should have all modules loaded - search for each module in the page to see if it was loaded (if the module does not appear, it was not loaded at all).

If some modules are missing, you need to investigate why. The best method is to turn off all modules, then restart Apache. Then, enable them one by one, restarting Apache each time, to see where things go wrong. When you have identified the culprit, use the web to find why the module will not load.

.. note:: We have used a trick in the previous step, namely the ``LoadFile "C:/Program Files (x86)/PHP/libpq.dll"`` configuration directive, for Apache to load the DLLs of PostgreSQL. PHP will simply not load them by default because PHP is broken on Windows. The trick forces Apache to load the DLL earlier than PHP, and then PHP happily uses it. If you let PHP do this by itself, it will fail - silently. Using ``.msi`` installation packages does not prevent the problem to happen, and worse, it will clutter your PATH with stupid values, making the issue even worse.

.. _tbs-win7-pg-setting:

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

PiAnoS need multuples libraries to run. The different libraries can be installed in the ``backend`` folder, or in the php_shared folder (prefered method).

In this case, the libraires will be installed in the ``./backend`` folder. This installation can be done by cloning the Git repo OR downloading the released archive from the Git repo:

.. code-block:: bash

	$ 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, or in directly in the "backend" 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

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

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

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 4 (from your start menu)
	- In the Object Browser, double-click "PostgreSQL <version> (localhost:5432)"
	- Enter the password you have defined earlier
	- In the tree that has expanded, right-click "Login Roles" and choose "New Login Role ..."
	- Enter "pianos" as role name and choose a password (this password will be stored in plain text so it should be different from e.g. your mailbox password)
	- Validate with OK: the role is created
	- Right-click "Databases" and choose "New Database ..."
	- Enter "pianos" for the name, select "pianos" for the owner, check that encoding is **UTF8**
	- Validate with OK: after a while, the database is created

Allow the web application to connect to the database in the ``pg_hba.conf`` file. And near the end (order is important, ``pianos`` must come before ``all``):

.. code-block:: python

	[...]
	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

Download and unpack PiAnoS
------------------------------

.. note:: If your system does not know what to do with `.tar.gz` archives, we recommend you to use `7-zip <http://www.7-zip.org/>`_, a free file archiver that handles all common formats (its own `.7z` but also `.zip`, `.gz`, `.bz2`, `.rar`, `.iso`, etc.)

Download `src-latest.tar.gz <https://esc-md-git.unil.ch/PiAnoS/src/-/archive/latest/src-latest.tar.gz>`_ and unpack the content in ``C:\www``. This will overwrite our test ``index.php`` file - nothing to worry about.

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] even on x64 platforms, using 32-bit binaries for these is a safe bet for the moment
.. [#f2] there are alternatives to this, including switching to Administrator to edit the files (really boring: need to launch the text editor as Administrator and then open the file) and a cleaner version of my proposal (adding your user with full control instead of giving full control to everyone)
