Getting Started - Windows

From AuthPuppy Wiki

Created By Robin Jones, Last updated: 2011-03-09

Overview

This document is a new step-by-step tutorial covering the installation, deployment and functional test of the AuthPuppy on Windows Server 2008. This document is a modified version of this

In order to prepare for Internet deployment, the tutorial can be executed in a dedicated server environment, hosted on the Internet.

Of course, it's possible to complete the tutorial on a local server, or a virtual machine at the reader's workstation.

Reason for a this Tutorial

Currently, there are two sources of information related to Microsoft Internet Information Server (IIS) on the symfony website, however they refer to previous versions that have not evolved with newer versions of Microsoft Windows operating systems, especially Windows Server 2008(released in February, 2008), which includes many changes of interest to PHP developers:

IIS version 7, the version embedded in Windows Server 2008, was entirely rewritten to a fully modular design.
IIS 7 has proven to be very reliable, with very few fixes needed from Windows Update since the launch of the product.
IIS 7 also includes the FastCGI accelerator, a multi-threaded application pool that takes advantage of the native threading model of Windows operating systems.
The FastCGI implementation of PHP equates to a 5x to 10x performance improvement in execution, without cache, when compared to traditional ISAPI or CGI deployments of PHP on Windows and IIS.
Microsoft now has a cache accelerator for PHP, which is currently at version 1.1

How to play with this Tutorial on different Windows Systems, including 32-bit

This document was written specifically for 64-bit editions of Windows Server 2008. However, you should be able to use other versions without any complications.

The exact version of operating software used in the screenshots is Windows Server 2008 Standard Edition with Service Pack 2, 64-bit edition.

32-bit Versions of Windows

The tutorial is easily portable to 32-bit versions of Windows, by replacing the following references in the text:

On 64-bit editions: C:\Program Files (x86)\ and C:\Windows\SysWOW64\
On 32-bit editions: C:\Program Files\ and C:\Windows\System32\

About Editions other than Standard

Also, if you don't have Standard Edition, this is not a problem. This document is directly portable to other editions of Windows Server software: Windows Server 2008 Web, Enterprise or Datacenter Windows Server 2008 Web, Enterprise or Datacenter with Service Pack 2 Windows Server 2008 R2 Web, Standard, Enterprise or Datacenter editions.

Please note that all editions of Windows Server 2008 R2 are only available as 64-bit operating systems.

About International Editions

The regional settings used in the screenshots are en-GB.

This document should be compatible with all language versions of windows and users are encorraged to install the MUI packs of all potential customers to enable them to display different languages on websites.

It is possible to execute the tutorial on Windows client operating systems: Windows Vista and Windows Seven both in x64 and x86 modes.

Web Server used throughout the Document

The web server used is Microsoft Internet Information Server version 7.0, which is included in all Windows Server 2008 editions as a role. We begin the tutorial with a fully functional Windows Server 2008 server and install IIS from scratch. The install steps use the default choices, we simply add two specific modules that come with the IIS 7.0 modular design: FastCGI and URLRewrite.

Databases

At the moment Authpuppy is only designed to use MySQL and PostgreSQL Databases and due to its dependence on symfonys Doctrine plugin is currently unable to offer support for Microsoft’s SQL Server.

For the purpose of this document, we will setup and configure a MySQL database, however PostgreSQL has also been tested to work (please note that the PHP extension PHP_PDO_pgsql.dll would have to be enabled).

Windows Server Configuration

It is better to use a fresh installation of Windows Server in order to match the step-by-step screenshots in this chapter. Of course you can work directly on an existing machine, but you may encounter differences due to installed software, runtime, and regional configurations. It is possible to use any dedicated server with Internet access. A physical server or even virtual private server (VPS) will work perfectly. In order to get the same messages as outlined in this document, the operating system we used is: "Windows Server 2008 Standard Edition 64 bits". This is an x64 distribution, delivered with the en-GB locale. It's easy to switch from en-GB to fr-FR and vice-versa, or add other locales from the Windows Control Panel. Specifically, this setting can be found in the "Regional and Language Options", which lives under the "Keyboards and Languages" tab. Just click on "Install/uninstall languages".

It is mandatory to have Administrator access to the server.

If working from a remote workstation, the reader should run Remote Desktop Services (formerly known as Terminal Server Client) and ensure he has Administrator access.

The distribution used here is: Windows Server 2008 with Service Pack 2.

Screenshot of windows version:

Windows Server 2008 was installed with the graphical environment, which matches Windows Vista's look and feel. It is also possible to use a command-line only for version of Windows Server 2008 with the same services in order to reduce the size of the distribution (1.5 GB instead of 6.5 GB). This also reduces the attack surface and the number of Windows Update patches that will need to be applied.

Initial configuration tasks wizard

You should now complete steps 1 of the Initial configuration tasks wizard. This will be very dependent on your individual environment, setting your time zone, static IP address and computer name (if these settings were not supplied during windows setup).

Screenshot of Initial configuration tasks wizard :

You should now complete step 2 of the Initial configuration tasks wizard using the guidance below. During this stage you should turn on windows update and update the server with all the latest hotfixes and service packs.

Note: after applying the suggested updates and the computer has been rebooted, please check for further updates, as some newer updates won’t be displayed until others are installed.

Please keep automatic updates enabled whilst carrying out the whole installation procedure, once it is complete you can then choose to turn it off (at your own peril) or alternatively set an adequate update schedule (which will remain out of scope for this guide).

Screenshot of Windows Update :

For the time being we will skip step 3 of the Initial configuration tasks wizard, and will return to this at a later stage of the document.

Installing the web server components

Now, we can install IIS and PHP in one simple operation.

PHP is NOT a part of the Windows Server 2008 distribution; hence we need to first install the Microsoft Web Platform Installer 3.0, referred to as Web PI in the following sections.

Web PI takes care of installing all dependencies necessary for executing PHP on any Windows/IIS system. Hence, it deploys IIS with the minimal Role Services for the Web Server, and also provides minimal options for PHP runtime.

You can download Web PI 3.0 from here

Screenshot of Microsoft Web Platform Installer 3.0 :

The installation of Microsoft Web Platform Installer 3.0 contains a configuration analyzer, checks for existing modules, proposes any necessary module upgrades, and even allows you to beta-test un-released extensions of the Microsoft Web Platform.

Web PI 3.0 offers PHP runtime installation in one click. The selection installs the "non-thread safe" Win32 implementation of PHP, which is best associated with IIS 7 and FastCGI. It also offers the most recently tested runtime, here 5.3.5. To find it, just select the "Products" tab on the top:

In order for authpuppy to run efficiently, you should also select the following products:

IIS Recommended Configuration
URL Rewrite 2.0
PHP manager for IIS
Windows Cache Extension 1.1 for PHP 5.3

Note: although you can also take this opportunity to install other products from the web platform installer, it is advised that you wait until after completion of this guide, as it may affect the setup of IIS. You can now click install.

After selecting these products, Web PI 3.0 automatically selects all dependencies needed to service .php web pages stored on the server, including the minimal IIS 7.0 roles services:

Next, click on the "I Accept" button. The installation of IIS components will begin while, in parallel, The PHP runtime and other products are downloaded while some modules are updated (an update for IIS 7.0 FastCGI for instance).

Finally, the PHP setup program executes, and, after a few minutes, should display:

Click on "Finish".

The Windows Server is now listening and able to answer on port 80. Let's check this in the browser by typing "http://localhost" into the address bar:

Configuring PHP

This part of the guide will help you configure PHP correctly.

Adding PHP the environment path variable

Open the run prompt and type:

   control sysdm.cpl

Then select the "Advanced" tab and click on the "Enviroment Variables" Button

Add:

   C:\Program Files\PHP\v5.3\;

to the end of the path variable string.

Enabling Extensions

By default the PHP installation has 99% of the extensions needed to run authpuppy properly. there is one extension however that is not enabled, so now is a good time to enable it.

Open IIS Manager by typing:

  inetmgr

at the run dialog

click on your computers name from the tree on the left of IIS Manager

then double click on the PHP Manager icon

select php_xsl.dll from the disabled extensions (at the moment it should be greyed out):

then click enable from the top right hand side.

It should now display it as enabled:

PHP manager recomends fixes

Whilst we are in PHP Manager, it shows that there are some recommendations, click on the "View recommendations" hyperlink, tick the check boxes and click OK:

checking your php installation

We shall now check that php is working correctly using the PHP manager tool.

from within PHP Manager, click the "Check phpinfo()" hyperlink Click the OK button on the dialog box that appears:

Finally we will check that the Symfony framework will work correctly with what we have done so far.

Download check_configuration.php from the symfony website and save it to:

   C:\inetpub\wwwroot\

now open your browser and navigate to http://localhost/check_configuration.php

the webpage should show the following:

As you can see, there are 2 warnings, don't worry though as:

the Web accelerator is installed, but not recognised by this script
posix_isatty() only provides colouring to the commandline and is not used for authpuppy.

Installation and configuration of MySQL

Download MySQL Community Edition from the MySQL website, and select the MSI installer for your version of windows (x86/x64)

Run the installer, agreeing to the terms:

when prompted select typical options:

finally when prompted select the "Launch the MySql Instance Configuration Wizard" checkbox and click Finish.

when prompted select "Standard Configuration" and click next:

Make sure the "Install as Winows Service" is checked and that the service name is "MySQL". Also make sure that the "Include Bin Directory in Windows PATH" checkbox is checked, then click Next:

Enter a STRONG root password when prompted, and keep it in a safe place for later!:

When the installer has finished, open a command prompt and type (pressing <Enter> at the end of each command):

   mysqladmin -uroot -p create authpuppy

when prompted, enter your root password for MySQL (Hint: this is the password you entered during its installation). now type:

   mysql -uroot -p

and enter your root password again, then type:

  create user 'authpuppy'@'localhost' identified by '<ENTER A PASSWORD FOR YOUR AUTHPUPPY DB USER HERE>';

create your authpuppy database user substituting <ENTER A PASSWORD FOR YOUR AUTHPUPPY DB USER HERE> for what it says!! Last but not least type:

   grant all privileges on authpuppy.* to 'authpuppy'@'localhost' with grant option;

type

   exit

to logout of mysql

then

   exit

again to exit the command prompt...

MySQL and an authpuppy database are now configured.

Download and configuration of Authpuppy

Download the current release of authpuppy core from https://launchpad.net/authpuppy and save it to a directory.

at time of writing, the core was at 0.1.1-beta.

Extract it using a tool like 7Zip to

   C:\inetpub\

currently, the authpuppy installer is not compatible with windows. To remedy this we can patch preinstall.php until 0.1.1-stable is released.

download the patch from https://bugs.launchpad.net/authpuppy/+bug/721001/+attachment/1856764/+files/preinstall.php

and save it to

   C:\inetpub\authpuppy\web\

Setting the directory permissions

We now need to make sure that the apropriate directories are writable by IIS

Those marked with a * MUST be writeable for the system to work, others must be writeable for automatic installation of plugins, but these steps can all be done manually:

config* or at least config/authpuppy.yml*: because the config/authpuppy.yml contains the list of active plugins so they can be loaded at initialization time
cache*: Used at runtime by symfony to cache functionnalities and data
log*: The log directory
data*: The clear cache task (needed when installing or configuring plugins) needs write access to this directory
plugins: The directory where plugins will be installed.
web: Plugins may have assets (images, javascript, css) to publish to the web directory, so make sure it is writeable, otherwise you'll need to do this by hand.

open explorer and navigate to

   C:\inetpub\authpuppy

right click on the web directory and click properties

open the security tab and click the edit button

click the add button and enter

   IUSR

into the textbox

click the check names button and then click OK

in the permissions for IUSR box check the Allow Full Control checkbox then click OK

repeat for all the directories that need write permissions.

Adding the site to IIS

in IIS Manager, drill down to "Sites" using the treeview on the lefthand side. right click on it and select "Add Web Site..."

In the Add Web Site dialog add the following string in the Site Name text box:

   Authpuppy

add the following string in the physical path text box:

   C:\inetpub\authpuppy\web

optionally, if you wish to host multiple websites on this server add the web address used for your site e.g.:

   auth.mydomain.com

If you choose to enter the web address, you can now skip to "Adding A Virtual Directory"

If you didnt choose to add your web address you will face a warning about "The binding *.80 is assigned to another site..." for the moment, click yes.

If you didnt choose to add your web address, you should now disable the default website.

Click on "Default Web Site" on the connections treeview on the left and then click Stop on the Actions toolbar on the right:

Now click on "Authpuppy" on the connections treeview on the left and then click Start on the Actions toolbar on the right:

Adding A Virtual Directory

A requirement of Symfony id that you create a virtual path to the sf directory.

left click on "Authpuppy" on the connections treeview on the left and select "Add Virtual Directory..."

in the Alias text box enter:

sf

in the physical path text box enter:

   C:\inetpub\authpuppy\lib\vendor\symfony\data\web\sf

then click OK

you should now see that a shortcut to sf has been added in the web directory in the connections tree view

Test symfony

We will now run a couple of checks to make sure that symfony is running with the commandline.

open a command prompt and enter:

   cd C:\inetpub\authpuppy\

   php symfony -V

this should return:

   symfony version 1.4.0...

now enter

  php symfony cc

to clear symfonys cache

Conclusion

Configuring Authpuppy is outside of the scope of this guide, however by following this guide, you should have an optimised webserver running Authpuppy.

Enjoy!