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

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.

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

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.
	
	
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
		
	Note the forward slashes in the paths - this is not a typo, Apache requires forward slashes.
	
	- 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 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).

	- Start pgAdmin III (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 ..."
	- 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


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 `pianos-latest.tar.gz <https://ips-labs.unil.ch/pianos/downloads/pianos-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)

