Step-by-step installation on Windows

Note

This installation page is not updated as frequently as the Debian one. If you have some issues, also check the debian installation page to see if there is some differences in the explanations.

This chapter covers the installation on a Windows 64-bit system. The process is in essence the same as in Step-by-step installation on Debian Linux 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:

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. The installation should be done with the latest official installation guide provided by the PHP project. Here is a short summary:

  • 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 2. 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 2

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

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)

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

# [ ... ]
DocumentRoot "C:/www"
# [ ... ]
<Directory "C:/www">
        # [ ... ]

Finally, for convenience, set the DirectoryIndex to show index.php:

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

<?php
phpinfo();

  • Save the file, and point your web browser to http://localhost/index.php. You should now see the PHP Information page.

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.

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.

Configure the libraries

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

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:

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

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

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

Footnotes

1

even on x64 platforms, using 32-bit binaries for these is a safe bet for the moment

2(1,2)

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)