AzurePHP - Advanced Windows Azure Companion Guide

IMPORTANT NOTE - July 13, 2011

The Windows Azure Companion was an experimental tool to provide a simple experience installing and configuring platform-elements (PHP runtime, extensions) and web applications on Windows Azure. Preliminary feedback on this tool has informed the creation of a new set of tools to deploy applications to Windows Azure - available at http://azurephp.interopbridges.com/downloads

-----------------------------------------------------------------------------------------------------
THE FOLLOWING CONTENT IS NO LONGER CURRENT. REFER TO THE LINK IN NOTE ABOVE

Recommended Pre-read

Introduction and Installation
- Getting Started
- Downloading the Windows Azure Companion for PHP
- Contents of the Windows Azure Companion for PHP
Configuration
- Configuring the Windows Azure Companion for PHP
- Modifying the Companion Configuration File - CSCFG
- Deploying the Windows Azure Companion for PHP
- Configuring the Service with an Updated Configuration
- Configuring the PHP Service by Editing PHP.INI
- Resetting the Azure Companion
Services and Runtime
- Executing the PHP Service and the Administration Site
- Stopping PHP Service
- PHP Service Administration
- Installing PHP Runtime and Other Modules
Standard Applications
- Verifying PHP Service & PHP Applications
- Using the eXtplorer PHP Application
Custom Applications
- Creating a Custom PHP Application XML Feed
- Installing a PHP Application from an Updated XML Feed
- Application Update and Deletion Scenarios
Inner Workings & Troubleshooting
- The Role of Azure Storage in the Azure Companion
- Azure Companion VHD Analysis
- Common Errors

Introduction and Installation

Getting Started

Getting started using the Windows Azure Companion to deploying PHP runtimes, frameworks, and applications is as easy as 1, 2, 3.

Well, OK, it's really more like 1, 2, 3 - 4. ; ; The fourth step is enjoying the results.

Downloading the Windows Azure Companion for PHP

Finding the Companion

The Windows Azure Companion is easily found online at:

http://code.msdn.microsoft.com/azurecompanion/Release/ProjectReleases.aspx?ReleaseId=4956

The Windows Azure companion comes with a choice of several different Virtual Machines (VMs). You may select your choice of VM and download it by clicking on the appropriate link. The choice of VM is determined by your computing requirements and budgetary constraints; the larger the VM, the more resources it consumes, but also the more computing power that can be brought to bear.

It is always a good idea to download the Azure Companion source code, as well, in order to be able to understand the solution architecture. We will refer more to this later.

Contents of the Windows Azure Companion for PHP

For this example we have downloaded 4 sizes of VM:

Regardless of which VM you choose to download, the CSCFG file is always the same.

However, the CSPKG file differs between the VMs in the following respects:

This difference is related to the fact that the CSDEF file, a part of the CSPKG , differs between VMs:

WindowsAzureCompanion-ExtraLargeVM-Sep2010CTP

<WebRole name="WebRole1" vmsize="ExtraLarge">

WindowsAzureCompanion-LargeVM-Sep2010CTP
<WebRole name="WebRole1" vmsize="Large">
WindowsAzureCompanion-MediumVM-Sep2010CTP
<WebRole name="WebRole1" vmsize="Medium">
WindowsAzureCompanion-SmallVM-Sep2010CTP

<WebRole name="WebRole1" vmsize="Small">

The CSPKG file is not human-readable, so you will not be able to directly modify the contents; however, if you wish to build your own VM package, you may simply use the source code and rebuild it.

Once you have installed the Azure Companion, you will need to configure it.

Configuration

Configuring the Windows Azure Companion for PHP

For the purposes of this example, we will work with the Small VM. Here are the contents of the ZIP file:

First, open the CSCFG file in a text editor. This will allow you to make the necessary modifications to suit your application.

<?xml version="1.0"?>

<Setting name="ApplicationDescription" value="The <a href="http://www.microsoft.com/windowsazure/windowsazure">Windows Azure platform</a> is a cloud platform that allows applications to be hosted and run at Microsoft datacenters. It provides a cloud operating system called Windows Azure that serves as the runtime for the applications and provides a set of services that allow development, management and hosting of applications.

With its standards-based and interoperable approach, the Windows Azure platform supports multiple Internet protocols including HTTP, XML, SOAP and REST. As an open platform, the Windows Azure platform allows developers to use multiples languages (.NET, Java, and PHP & other dynamic languages ) to build applications which run on Windows Azure and/or consume any of the Windows Azure platform offerings.

The Windows Azure Companion aims to provide a seamless experience for deploying platform-level components as well as applications on to Windows Azure. The first community preview of the Windows Azure Companion has been tested with PHP runtimes, frameworks, and applications. However, the system may be extended to be used for deploying any component or application that has been tested to run on Windows Azure." />

<!-- MachineKey setting with ASP.NET machineKey XML.

You can generate an XML element with http://www.developmentnow.com/articles/machinekey_generator.aspx -->

</ConfigurationSettings>

</Role>

</ServiceConfiguration>

Within the CSCFG file, the editable settings fall into 3 different categories:

Must Edit Category: These are things that must be changed.

<!-Application Details. Title and Welcome text -->

Suggested Edit Category: These are things that are advisable to change.

<!-- MachineKey setting with ASP.NET machineKey XML.

You can generate an XML element with http://www.developmentnow.com/articles/machinekey_generator.aspx -->

Optional Editable Category: The rest of the settings you may edit to suit your requirements, or not, as you see fit.

Modifying the Companion Configuration File - CSCFG

Now edit your settings. The default values to be changed are shown in yellow highlight, below.

General Application Settings:

Setting Application Title: Modify the default title, to suit your application.
<Setting name="ApplicationTitle" value="My PHP Service on Azure" />
Setting Application Description: Modify the default description to suit your application.
<Setting name="ApplicationDescription" value="This is my PHP Test Service"/>

Azure Storage Settings:

Setting Azure Storage Account Name: Insert your account name.
<Setting name="WindowsAzureStorageAccountName" value=" happybuddha" />
Setting Azure Storage Account Key: Insert your account key.
<Setting name="WindowsAzureStorageAccountKey"
value="dyjrnWG0/ibgI4k9/j6DSZqyhCK5QlZDVYgwqyFqrH8IXW8od9XY1s1TyiDB+1nPCLrT2LOrx34TyhmsI7YyVg==" />

PHP Administration Settings:

Setting PHP Admin Account User Name: Insert your admin account name.
<Setting name="AdminUserName" value="MyName" />
Setting PHP Admin Account Password: Insert the password.
<Setting name="AdminPassword" value="MyPassword" />
Setting PHP Admin Account Email Address: Insert your email address.
<Setting name="AdminEmail" value="my-email-address@microsoft.com" />

PHP Applications XML Feed:

This is a very important feature of the Azure Companion, in which you will create the XML for an application feed and add your PHP related product in this feed format. This will allow you to install your application on Azure immediately as soon as the service is ready.

Application Feed Schema

Please refer to the WACompanionFeedSchema.pdf for detailed documentation of the application feed schema used by the Windows Azure Companion.

Please use the following value as your XML Feed to start your work:

http://wazstorage.blob.core.windows.net/azurecompanion/default/WindowsAzureCompanionFeed.xml

PHP Product List XML Feed Setting: Insert the feed value from above.

<Setting name="ProductListXmlFeed" value=" http://wazstorage.blob.core.windows.net/azurecompanion/default/WindowsAzureCompanionFeed.xml" />

In the section entitled "Windows Azure Custom Applications", under "Creating a custom PHP application XML Feed", you are shown how to create your own XML Feed.

If you look up the contents of the XML Feed, you will see the following applications:

PHP Runtime
PHP Wincache Extension
Microsoft Drivers for PHP for SQL Server
MariaDB
Windows Azure SDK for PHP
phpBB
Wordpress
phpMyAdmin
eXtplore File Manager

After incorporating your changes, the contents of your CSCFG file will look something like this:

Deploying the Windows Azure Companion for PHP

For this example, we have created an Azure service name "PHPAzure" on Windows Azure portal. The account looks like this:

The service URL will therefore be:

http://php-azure.cloudapp.net

Next, we upload the CSPKG and CSCFG files to the staging slot:

When deployment is complete, you will see the Ready indicator next to your role:

Configuring the Service with an Updated Configuration

To update the Service Configuration we can just update the configuration only; we don't need to redeploy the CSPKG.

Once you have decided to update the configuration, please be sure that you don't have any applications running anywhere. If you do, then please close all PHP services.

Let's suspend the service first:

After service is suspended, select "Configure":

Now "browse" to the updated CSCFG and upload it:

Verify that the update XML Feed is visible there:
Once you are sure, select the "Save" button, then confirm the configuration update.

You will see that the Service update is in progress:

Once the deployment has finished updating, you may restart the service by selecting "Run":

When the service is ready, run the service in Admin mode to check your sample application.

Configuring the PHP Service by Editing PHP.INI

If you wish to change the PHP runtime behavior, you need to first stop the service, modify the PHP.INI file, then restart the service. To edit PHP.INI, go to the Admin tab and select "Configure Runtime".

After modifying the PHP.INI, select "Update". Then restart the service.

Resetting the Azure Companion

Resetting means removing everything you have configured on the Azure virtual hard drive (VHD) and returning the service back to its original settings.

To reset the Companion, go to the Admin tab and select "Backup and Cleanup". Then select "Reset":

Since this process will remove everything on the virtual hard drive (VHD), it usually takes quite a long time; please be patient.

Once you have configured the Azure Companion, you will need to be able to use the services and runtime.

Services and Runtime

Executing the PHP Service and the Administration Site

Let's launch the web URL: http://php-azure.cloudapp.net

You will note that there is, as yet, no content on the web page. This is completely normal and to be expected. Now launch the service in Admin mode, using the same URL on port 8080:

http://php-azure.cloudapp.net:8080/

Actually, the PHP Administration is already part of the PHP project and it is configured to use port 8080 to run. ; If you deployed to a production slot the admin URL would be:

http://<your_PHP_Service_name>.cloudapp.net:8080/

Stopping PHP Service

To stop the PHP service, go to the Admin tab and select "Configure Runtime". ; Select "Stop" to stop the service. ; Select "Restart" to start the service. ; If the service is not already stopped, this will first stop, then restart the service.

PHP Service Administration

URL: http://<your_PHP_Service_name>.cloudapp.net:8080/

Select the Admin tab and enter the user name and password that you entered in the CSCFG file:

If your information is correct you will be logged into PHP Admin portal:

If you select any of the sub-menu items; i.e., PHP Logs or Cron Jobs you will not see any details, as none of the services have yet been configured to run.

You may look at the "Performance Monitor" sub-menu to see the physical RAM pressure details:

Installing PHP Runtime and Other Modules

The next step is to configure the PHP runtime and other necessary platform modules. For this purpose we will select the "Platform" tab from the admin mode. Once PHP is ready and we need to deploy any given PHP solution in the XML feed we will select the Applications tab.

Now let's take a look at the Platform main menu tab:

Above, you can see lots of options; however, to get PHP running, we will select the highlighted ones:

RunTime
- PHP Runtime
- PHP Wincache Extension
SDKs
- Windows Azure SDK for PHP

Once you have marked the checkbox for the above modules in the Platform tab, select "Next".

You will see the confirmation screen shown below before the final installation will start. This window will show you the selected application version that is provided in the XML feed.

Once you are satisfied with your selection, select "Accept". ; You will see a progress window, as below, with lots of log information about installation progress and results.

Finally, once the installation is complete, you will see the completion window:

Above, you can see that the installation was successful. ; It will also print the version and time when the installation was completed.

If you go back to the Admin tab and select "Windows Azure Logs", you will find detailed logs about the installation, regarding each selected module:

Once the PHP runtime is installed, you may launch the main service URL to see that PHP is successfully running. ; This is necessary to be able to launch standard applications.

Standard Applications

Verifying PHP Service & PHP Applications

To verify that the PHP service is running we can launch the main service URL:

PHP Web Service URL: http://<Your_Service_URL>.cloudapp.net

In our case the URL is: http://php-azure.cloudapp.net as below:

(If you are wondering where the page contents are coming from, just wait a bit, and we will explain presently.)

This page is actually the output from a very powerful PHP function:

<?php

phpinfo()

Since the PHP is service is running, we can use the Application tab to install the applications, as provided in the XML feed. ; Select the Application tab from PHP administration section.

The particular XML feed that we select comes with 3 applications and 1 utility:

We will not install any of the applications at this point; however we will install the eXtplorer utility, which will be very helpful in managing our service.

Mark the eXtplorer utility checkbox and select Next: You should see the confirmation window:

- It shows that eXtplorer version 2.1.0RC1 is going to install in the /extplorer directory.

Once installation is started you will see a progress window:

Once installation is completed you can see the confirmation:

Using the eXtplorer PHP Application

You may launch eXtplorer as follows:

eXtplorer URL: http://<Your_Service_URL>.cloudapp.net/extplorer

The default user name and password for eXtplorer are both "admin"; enter it correctly:

Once you have selected the username and password, please select Login and you will see the eXtplorer shell opened in the same window with an important notification:

The notification is a reminder to change your password, otherwise anyone using this utility can modify your PHP application files and their contents.

Select OK in the above window and you will see the Change Password window appear:

Please enter your new password, then go ahead and select Change. You may also add more users to your website by selecting the Users tab in the Administration dialog window.

Once your password has been changed, you will see the eXtplorer shell running:

If you recall the PHP main page at php-azure.cloudapp.net, you will find that it is actually rendered from the file phpinfo.php, from the file location seen in eXtplorer.

The eXtplorer utility is a tool to add or remove files and folders in your PHP service, in real time. We can see this best from some examples:

Example 1: Uploading a file from local machine to Azure

Let's create a PHP file named "echo" on your local machine:
Copy the file to the PHP Service:
Now launch the file in a web browser:

Example 2: Downloading a file from Azure to a local machine

Select a file from the list, and then click the Download button:
Depending on your particular web browser, you will either be prompted to save the file in a certain location, or the file will be downloaded to a predefined folder on your local machine.

Example 3: Editing a file on Azure

Select a file from the list and then click the Edit button:
The file will be opened in the editor: (We have added one more line to it.)
Now save the file by clicking the Save button and you will see the Success message:
Now launch the file in the browser to see the changes:

Please spend some time to familiarize yourself with the eXtplorer toolbar:

When you are done, remember to logout using the logout button:

Note: While writing this tutorial, IE9 was not yet supported with eXtplorer, so please use an older version of IE, or another make of browser.

In addition to standard applications, you will want to be able to install custom applications.

Custom Applications

Creating a Custom PHP Application XML Feed

Now we will demonstrate how to create an XML feed for your project, and add any necessary modules.

Please refer to the WACompanionFeedSchema.pdf for detailed documentation of the application feed schema used by the Windows Azure Companion.

Things that you will need include:

Your complete PHP project, in a zip file uploaded to an internet location, from which it is directly downloadable.
If you wish to add a license file with your project, then the license file should also be available on a directly accessible internet location.

Example; Creating a PHP Project:

Begin with a PHP file named hello.php and an image, Avkash.jpg as below. When launched, the hello.php file shows the image Avkash.jpg.

Creating the PHP Project ZIP file:

Create a zip file, named ShowImagePhp.zip, which contains the files hello.php and Avkash.jpg:

Create a license file:

Create a license file, ShowImagePHPLicense.txt, as shown below:

Uploading the PHP Project ZIP and License file on Azure Storage:

The next step is to upload these files to a publicly accessible storage location from where they can be downloaded. As you may remember, we have already created an Azure storage name, "happybuddha", so we can use the same Azure storage for these files. We'll create a new directory, named projectfiles, and copy both files into this location.

Both the files are shown in the following, "CloudBerry Explorer for Azure Blob Storage" view of our happybuddha storage and projectfiles directory:

So based on the above, we can derive the following URLs for:

Project ZIP URL
1. http://happybuddha.blob.core.windows.net/projectfiles/ShowImagePHP.zip
Project License file URL
1. http://happybuddha.blob.core.windows.net/projectfiles/ShowImagePHPLicense.txt

Note: Please verify that the above links are working properly.

Now we will create an entry for our project. So before we go further let's decided what is needed:

Product ID
Product Category
Install Category
Product Title
Product Summary
Product Tab (in which this application will be listed on PHP Admin page)
Product License URL
Product Installation properties
Product installer location
Product Dependencies (This is needed to be able to install other products first )

So based on our project information we have the following details:

Product ID : ShowImagePHP
Product Category: Web Applications
Install Category: Web Applications
Product Title: Show Image PHP Application
Product Summary: This is sample PHP project to show the Feed XML
Product Tab: Applications
Product License URL: http://happybuddha.blob.core.windows.net/projectfiles/ShowImagePHPLicense.txt
Product Installation properties:

/ShowImagePHP

Product installer location:

http://happybuddha.blob.core.windows.net/projectfiles/ShowImagePHP.zip

Product Dependencies: (Because this is a PHP web site so it will need PHP runtime at minimum)

PHP_Runtime

Based on the above details, the Entry XML should look like this:

<entry>

<productId>ShowImagePHP</productId>
<productCategory>Web Applications</productCategory>
<installCategory>Web Applications</installCategory>
<updated>2010-10-14T12:00:00Z</updated>
<title>Show Image PHP Application</title>
<tabName>Applications</tabName>
<summary>This is sample PHP project to show the Feed XML</summary>
<licenseURL>http://happybuddha.blob.core.windows.net/projectfiles/ShowImagePHPLicense.txt</licenseURL>
<productProperties>
<productProperty name="installPath" caption="Installation Path" defaultValue="/ShowImagePHP" />
</productProperties>
<installerFileChoices>
<installerFile version="1.0" url="http://happybuddha.blob.core.windows.net/projectfiles/ShowImagePHP.zip" />
</installerFileChoices>
<dependencies>PHP_Runtime</dependencies>

</entry>

The next step is to create a feed where our PHP application is visible to the PHP service so we can install in the same way that we have installed "PHP Runtime" and ""eXtplorer" previously. Here are the steps to follow:

We will use the same default PHP companion XML Feed, so we will download it first.
We will add a new entry with your project name and attributes to the same XML feed. and
We will upload the feed and the project resources to an Azure Storage location so it is available on the Internet.
Finally, we will modify the CSCFG file with the new path of the XML Feed location, so that our application is available to install.

Creating an XML Feed for our project:

First, let's download the default XML feed from the Azure companion Location, save it to the local machine and then open it for editing, to add our XML entry.

http://wazstorage.blob.core.windows.net/azurecompanion/default/WindowsAzureCompanionFeed.xml

We have added our Entry content to the XML, as follows:

Now save this to a new XML file as:

WindowsAzureCompanionFeedAvkash.xml

Next, we upload this file to the Azure Storage "happybuddha" and then derive the web URL for it.

The web URL for our XML Feed is:

http://happybuddha.blob.core.windows.net/projectfiles/WindowsAzureCompanionFeedAvkash.xml

Opening this XML Feed in a browser, we can see our PHP Project at the top:

Editing ServiceConfiguration.cscfg

Let's go back to the file, ServiceConfiguration.cscfg, and add the new XML feed location:

Finally, we save the modified ServiceConfiguration.cscfg.

(There are other parameters in this file, so you may edit them, if needed.).

Installing a PHP Application from an Updated XML Feed

After the service is ready, launching the web URL should bring up the previous running content; this is because we have already installed the PHP runtime and eXtplorer, and since the virtual hard drive (VHD) is still the same, everything installed previously is still accessible:

http://php-azure.cloudapp.net/

Now let's go to admin mode to verify that our "PHP Sample Application" is visible so we can install it:

(We have edited the above image to show only the sample PHP project on top; otherwise it would be listed below the other PHP Web Applications.)

Now please select the Show Image PHP Application checkbox, then select "Next":

This shows that we will be installing version 1.0 at the location "ShowImagePHP". Once we have verified the information, select Accept.

The project ZIP file should now get downloaded:

When the installation is complete, the service will show the completion status:

Now we can view our "Show Image PHP Project" on Azure as a specific URL:

http://php-azure.cloudapp.net/showImagePHP/hello.php

If you try the following URL , you will note that this does not render any web content:

http://php-azure.cloudapp.net/showImagePHP/

The error occurred because when you launch a web site from a folder, it tries to launch the default settings page; i.e., index.php, default.php or index.asp, etc. Because hello.php was the only file in our project zip file, there was no default page; hence the error.

So to solve this problem, let's add the file index.php.

Open the eXtplorer shell and go to our project directory, "ShowImagePHP":

Then select the New File/Directory icon:

Enter the file name, "index.php", select the type "File" and click the Create button.

Once the file has been created, select index.php from the list, and click the Edit button. The file will open in the editor. Type the following text in it:

When finished, click the Save button at the top, to save the file.

Afterwards, you can see the content in the web URL:

By selecting the "Show Image" hyperlink, you can see the content:

Application Update and Deletion Scenarios

During your PHP project development, it is possible that you may have to either delete your project or update the project.

To Delete a PHP web application:

There is no turnkey or just "select and click" functionality to delete a PHP web application, once installed by an administrator. To delete a PHP web application you can try any of the following, or a combination thereof:

A full Reset of the Service.
Use eXtplorer to manually delete the PHP web application.
Stop the Azure Service and then delete the VHD on Azure Storage.

To Update a PHP web application:

If you wish to update a project you have several options:

Deploy a new ZIP file:
1. First, Stop the Azure Service.
2. Delete the VHD at Azure Storage by removing the phpapps folder.
3. Update the PHP Web Application Zip file.
  - Either Update the XML Feed with a new, updated ZIP location, or
  - Update the same ZIP file with updated content.
4. Update the Configuration on the Azure Portal.
5. Restart the service.

Use eXtplorer to add your project; however:
1. It might be cumbersome if you have lots of files to deploy.
2. It is very convenient if you have only simple modification within a few files; ; i.e., settings, etc.

Inner Workings & Troubleshooting

The Role of Azure Storage in the Azure Companion

You may wonder what the role of Azure Storage is, in the overall solution. We would suggest that you look at the Azure Storage which you have used in this application.

Below, you can see in Azure Storage, where a new container name, "phpapps" has been created:

Upon opening phpapps, you should see the following:

Looking at the above should give you the idea that the PHP solution creates this virtual hard drive (VHD) on Azure Storage, and all PHP platforms, applications, utilities etc., are, in turn, installed on this VHD. This VHD is mounted with the service, so when we access PHP, the application installed on this VHD is visible to us. Consequently, when you use the web URL, http://<your_php_service>.cloudapp.net, the file located on this VHD actually renders on your browser.

Azure Companion VHD Analysis

After copying the virtual hard drive (VHD) to the local machine and then mounting it, you may note that it contains all the modules, i.e., platform, web application and utilities, that you installed when you ran the service in the admin mode.

First, download the file backup.vhd to the local machine:

There are several ways you can attach a VHD to your machine, so, once you have attached it, you may open the VHD in your file browser:

The PHP runtime is installed in the root php folder. Opening the application folder we can see:

All the application and utility installations were done in the application folder.

This way you can look around the files and folders. ; You can also update the contents in the virtual hard drive (VHD) and then update back to Azure Storage when Azure Service is stopped.

Common Errors

[1] Service does not show any content
Reason: The PHP is not configured yet.
Solution: Configure the PHP Runtime to get PHP Working on your Service.
[2] HTTP Error 404.0 - Not found
If you encounter this error when launching the service:
Reason: The VHD could not mount, consequently the files are not available.
Solution:
Make sure that the Azure Storage used in this PHP solution is not be used in other PHP solutions; otherwise the VHD may be mounted with other service and you could not use in this service.
If you have verified that this is the only service that uses the VHD, and you still see the error, then give the system some time to get the VHD mounted. Sometimes the VHD mount process takes longer than expected and can cause this error.
[3] "Installation Failed Error: Could not find a part of the path 'B:\php'.
When you try to install any application or utility from the PHP Administration site you may get the error:
Reason: It means you are hitting error #2.
Solution:
Check to see if the service is active, using service web URL:
http://<your_php_service>.cloudapp.net
Follow all other suggestions given for error #2.

Advanced Windows Azure Companion Guide

Table of Contents