UPDATE June 4, 2012: Microsoft has released a new solution for PHP hosting in a Linux environment on Azure. As a result this entire tutorial is now defunct as there is a better and much easier solution available. Check it out right here.

UPDATE November 2, 2011: The WordPress on Azure scaffolder has been updated and a new and easier process has been introduced. In response this tutorial has been rewritten to reflect the new methods.

In this step-by-step tutorial I’ll take you through the process of publishing a single-site deployment of WordPress on Windows Azure. By “single-site deployment” I mean that you’ll be using WordPress as one single site. In contrast a Network deployment refers to a situation in which you’ll set up WordPress and then run multiple sites under it in a network.

A step-by-step tutorial on how to deploy WordPress Networks on Windows Azure will be posted in the near future.

What you’ll need

• Windows Azure account (get a free trial here)
• Windows Azure SDK (total pain to install so I suggest you use Web Platform Installer)
• FileSystemDurabilityPlugin
• Windows Azure SDK for PHP
• PHP
• WordPress on Windows Azure scaffolder tool
• Optional: The plugin(s) you want to use
• Optional: The theme(s) you want to use

The two last points are optional, but it’s always a good idea to install WordPress with the plugins and theme(s) you want to use right off the bat. It saves you a bit of time later on.

Note that the following assumes you have a Windows Azure subscription. If not, go to the Windows Azure website and get a free trial.

1. Setting up Azure

The first step in deploying WordPress on Windows Azure is to set up the necessary elements in the Windows Azure environment. This is all done through the Windows Azure Management Portal found at http://windows.azure.com. For the deployment you’ll need a new Hosted Service, dedicated Blob storage and a database.

1a. Create a new Hosted Service

Your WordPress deployment will live in a Hosted Service on Windows Azure. You can have multiple Hosted Services under one account. To set up a new Hosted Service log into the Windows Azure Management Portal and click the New Hosted Service button in the top left corner.

This opens the New Hosted Service dialog where you can define the different parameters of the hosted service as seen below:

Off the top you select what subscription you want the new Hosted Service to live under.

Next give it a name so you know what it’s about and enter a dedicated URL prefix for your application.

By default all Windows Azure applications have a URL that looks like http://something.cloudapp.net. You can change this by forwarding one of your own domains to this address. More on that later.

Under Choose a region or affinity group you define in what general geographic area the application will be used. Pick the region or affinity group that is closest to your users.

When setting up a new Hosted Service you can deploy an application immediately. But since we have yet to build a deployment, check Do not deploy and click OK.

Windows Azure now runs a process and when it is completed you should see your new Hosted Service on the list as seen below.

1b. Create a Storage Account (Blob storage)

We’ll be using a Blob Storage Account to host all the uploaded content as well as the plugins and themes so that if and when your Windows Azure deployment reboots or reimages you don’t loose all this content. To create a Storage Account click on the New Storage Account button in the top left corner.

This opens the Create New Storage Account dialog as seen below:

Again pick the subscription you want to host the storage under, enter a URL prefix and set the region or affinity group. Make sure to place the Storage Account in the same region or affinity group as the Hosted Service.

Windows Azure runs a process and when it is completed you should see your new Storage account on the list as seen below.

1c. Create a Database

The final step in the Windows Azure setup process is to create a database. This is where all the actual content of the WordPress site will live. This is a two step process: First you set up a new Database Server and then you set up a new database within it.

To create the new Database Server click the Database button on the lower left and click the huge Create New SQL Windows Azure Server button under Getting Started. Alternatively you can select the correct subscription and then click the Create button on the top toolbar. This opens the Create Server dialog. This is again a multi-step process.

First select the region (again, pick the same region you chose for the Hosted Service and Storage).

On the next screen set the username and password for the server. This is the info you’ll use to interact with the databases on the server so make sure you have a copy of it somewhere. You can edit it later but it’s a big pain.

The next step is interesting. You can assign custom IP addresses that are allowed to access your database directly. That’s not necessary in our case, but it could be in the future. For now just check the Allow other Windows Azure services to access this server box so WordPress can read and write to to the database. This will add a new rule with the IP range 0.0.0.0.

When you click Finish, Windows Azure will create the new database server. When it’s done it will appear with a weird computer generated name on your server list as below.

With the database server set up you can now create a database for WordPress. To do this select the new database server and click the Create Database button on the top menu. This opens the Create Database dialog seen below.

In the dialog give the database a name (this is the name you’ll call from the WordPress config file, define the type (edition) of database you want (the options are Web and Business of which I use Web) and set the maximum size. If you’re running a single install WordPress site I’d be flabbergasted if you ever managed to get the database up to 1GB so stick with that.

Click OK and Windows Azure creates the database. You’ll notice that there are two databases in the server, one called Master and the one you created. This is as it should be. You can manage, drop and mess with the database you created all you want but you should leave Master alone.

2. Preparing your computer for the build

Before creating your WordPress on Windows Azure deployment package you need to install the Windows Azure SDK, the File System Durability Plugin and the Windows Azure SDK for PHP. The Windows Azure SDK is necessary for your computer to be able to build an Windows Azure deployment package. The File System Durability Plugin does exactly what it says – ensures file system durability. This is necessary because in Windows Azure you can spin up and down several instances of the same site and we have to make sure the instances are identical all the time. The Windows Azure SDK for PHP contains the functions necessary to build custom Windows Azure deployments that depend on PHP.

The easiest way to install the Windows Azure SDK is to download Web Platform Installer, search for “Azure SDK” and install it using the tool. Web Platform Installer will do all the heavy lifting and configurations for you in one clean sweep. If you really want to you can also install the Windows Azure SDK manually but I’m going to warn you up front that it’s a pain unless you are very familiar with IIS and other Windows obscura.

To install the File System Durability Plugin download the zip file from Github and extract it into the Windows Azure SDK plugins folder found at:

C:\Program Files\Windows Azure SDK\v1.x\bin\plugins

Finally to install Windows Azure SDK for PHP simply download it and place the contents of the trunk folder somewhere on your computer. I created a folder called “Windows-Azure-SDK-for-PHP” in my Program Files folder for this. For what we are doing the SDK for PHP requires no installation, it just has to live on your computer in a place you can remember. If you want it to be a permanent feature on your computer you can follow the instructions at this site for a more advanced install.

3. Creating the WordPress on Windows Azure scaffolding

The following assumes you have already installed Windows Azure SDK, the FileSystemDurabilityPlugin, Windows Azure SDK for PHP and PHP.

With Windows Azure set up it’s time to create the WordPress deployment package. This is done using a “scaffolding” tool created specifically for this purpose. The tool is baked into the Windows Azure SDK for PHP. The basic idea of the scaffolding tool is that it builds the framework in which we will build and configure the final deployment package. Once the scaffolding is created we can configure and add content such as plugins and themes to the WordPress core before deploying it.

To make this process as easy as possible the Microsoft Interoperability Team has created a complete solution for us, available from Github. Download the entire package where you want to do the setup for your deployment and let’s get started.

The actual building of the scaffolder will be done in Command Line (Start -> CMD) in Administrator mode. You can start it from the Start Menu (remember to right-click and select Run as Administrator).

Before running the scaffolder command you need to include the Windows Azure SDK for PHP in the system environment. This can be done by tweaking your system settings, but if you want a quick and easy way that leaves your system settings alone you can just configure it for the current open command line window using this command:

SET PATH=%PATH%;c:\PHP;C:\Program Files\Windows Azure SDK for PHP\bin

(The above assumes PHP is installed in the PHP folder on C: drive and the Windows Azure SDK for PHP is installed in the Windows Azure SDK for PHP folder under Program Files. Your command may be different depending on where you installed PHP and Windows Azure SDK for PHP.)

With the system settings changed it’s time to run the scaffolder. You can do this manually or you can use the convenient new build.bat batch file that will run the entire process for you. In command line type:

build.bat

If you’ve kept all your ducks in a row up until this point the scaffolder will now run and you’ll see a bunch of prompts in the command line window. The scaffolder sets up the entire environment you need to get WordPress to run on Windows Azure, downloads the latest version of WordPress automatically and adds a couple of very important WordPress plugins to boot. Pretty nifty.

When the command completes you’ll have a new folder called “build” in the same folder where build.bat was located. The build folder in turn contains three files: ServiceConfiguration.cscfg, WordPress.cspkg and WordPress.phar in addition to a folder called WordPress.

4. Configuring the WordPress for deployment

With the scaffolding built it’s time to configure WordPress. If you’ve ever worked published a WordPress site before you know that you need to plug in database access info and other data in the wp-config.php file before deployment for the site to hook onto the database. In the case of WordPress on Windows Azure however, that information is placed in an Windows Azure configuration file and the wp-config.php file queries this configuration file for the details. This allows you to change the configuration of the WordPress installation on the fly through the Windows Azure deployment configuration panel rather than having to redeploy every time you want to change something. The file in question is found in the build folder and is called ServiceConfiguration.cscfg. Open ServiceConfiguration.cscfg in a text editor and make the following changes as outlined below:

Database info

DB_NAME is the name you set for the database, in my case “PhotoPivotDB”

DB_USER is your Windows Azure username combined with an @ and the name of the database server as assigned by Windows Azure. The full user name looks like this: “mor10@k3b1ogbnc7″

DB_PASSWORD is the password you defined when setting up the server.

DB_HOST is the host name of the server combined with .database.windows.net, so for example k3b1ogbnc7.database.core.windows.net

Security keys

With the new build.bat file the security keys are automatically generated so you no longer have to worry about them unless you want to add more complicated encryption.

FileSystemDurabilityPlugin settings

This section relates to the FileSystemDurabilityPlugin. Here you provide the access info to the Blob storage you set up earlier:

StorageAccountName is the name you gave your storage, in my case ppwpstorage

StorageAccountPrimaryKey you get by going to the Windows Azure portal, clicking Hosted Services, Storage Accounts & CDN, selecting your storage and clicking the Primary Access Key button on the top right hand corner:

This opens a dialog from which you can copy the access key. It ends with two equal signs (==)

Leave everything else as it is.

5. Create the Deployment Package

The core setup is now complete and we are ready to create the deployment package. If you want to add any custom plugins or themes to your deployment, this is the time to do so. You find the plugins and themes folders under the \build\WordPress\WebRole\wp-content\ folder where you can add them by simply dropping them in. This is also where you add new or changed files when you are going to redeploy.

To ensure that WordPress can send administrator emails I recommend you download and add the WP Mail SMTP plugin. As Windows Azure does not have a native email server you need to use an external SMTP server to handle WordPress’ emails. This is further covered at the end of the article but since you’ll want the mail function to work you will save time by adding the plugin now so it’s part of your deployment package.

Creating the package is the final step before deploying to Windows Azure. Like with the scaffolder, the packager is run in comman line. First, navigate to the build folder where you find the WordPress.phar file. Then run the as follows:

package create -in=".\WordPress" -out=".\package" -dev=false

The process runs and you should end up with a new folder called package with two files: WordPress.cspkg (named after the export folder) and ServiceConfiguration.cscfg.

6. Deploying the Package

To deploy the package log in to the Windows Azure Portal, go to Hosted Services, Storage & CDN, click Hosted Services and select the hosted service you created earlier.

Next click the New Production Deployment button in the upper left corner. This opens the Create a new Deployment dialog:

Give your deployment a name and point the Package location to your WordPress.cspkg file and Configuration file to ServiceConfiguration.cscfg, both in the package folder.

Click OK and if everything is correct you’ll get a warning like the one below. Click OK and the package will be uploaded and deployed. Because the build file will be at least 15mb in size this may take a bit of time.

Once the package is uploaded you have to wait for Windows Azure to do its thing. This can take quite a long time (I’ve seen it take over an hour!) You just have to be patient and wait for it to do its thing.

7. Setting up WordPress on Windows Azure

If everything went as planned you should see the Deployment, Role and Instance of your deployment change to Ready. If so you can click on the deployment and you’ll get the DNS name you set in step 1a (http://something.cloudapp.net). Visit this address and you’ll get the standard WordPress setup screen.

Here you fill out all the standard stuff like Site title, username, password and an email address. Before clicking Install WordPress, make sure you remember your username and password! As Windows Azure doesn’t have an email server WordPress will not send you an email with your username and password nor will it do so if you click the “I forgot my password button”, so be careful.

After hitting Install WordPress the application is installed as normal and you get to the login screen. From here we have to do a couple of extra things before we’re all set to go:

7a. Set up Windows Azure Storage for WordPress

WordPress normally stores all uploads in the wp-content/uploads folder and this works fine on a normal server. But Windows Azure is a virtual server environment so things don’t work the same way. This is especially true when it comes to uploads. Because your WordPress instance (or instances) on Windows Azure live on a virtual server that can be reset and re-imaged, the WordPress on Windows Azure solution has to create synced copies of the wp-content folder in Blob storage so that all instances are identical and resets are not destructive. That means if you have a ton of images or other files on your site, these will be constantly passed back and forth between your instances and Blob, and that will become costly.

To get around the problem the WordPress.phar file ships with an extra plugin called Windows Azure Storage for WordPress. This plugin allows you to use Blob storage to save media in your installation.

Before activating the plugin you need to assign a container in your Blob storage for your uploads. The easiest way to do this is to use a tool like CloudXplorer and set it up manually.

To activate go to Plugins and activate Windows Azure Storage for WordPress.

Then go to Settings and select Windows Azure. This takes you to the configuration page for the Windows Azure Storage for WordPress plugin.

Here you need to plug in the storage account name and the access key for the storage account. I use the same storage as for WordPress itself so I just copy the info out of my ServiceConfiguration.cscfg file and paste it in. If you want to you can set up separate storage as well but it seems excessive.

If you want to you can define an alternate CNAME for your storage (by default the domain for your Blob storage is http://YourAccountName.blob.core.windows.net/) and even set up proxy server info. I’ll leave that for you to decide.

Lastly remember to check the Use Windows Azure Storage for default upload box.

With everything set click Save changes and the plugin will connect to your storage.

At this point the Default Storage Container filed will be populated with whatever storage containers are available in Blob storage. Pick the container you set up for your uploads using CloudXplorer and click Save changes again.

Now you should be ready to go. Just to make sure, go to Media, upload an image and make sure it works and that the URL points to Blob storage.

7b. Set up an external SMTP server

The final compulsory step in setting up WordPress on Windows Azure is to set up an alternate SMTP server for the application so it can send emails to you and others. This is important because WordPress uses emails to communicate with you about things you need to know such as new user registrations, new comments and most importantly how to retrieve your username and password when you forget.

Setting up an SMTP server can be done using any one of a number of plugins. We use the WP Mail SMTP plugin by Callum MacDonald on PhotoPivot.com and it works splendidly. The setup of this plugin is self-explanatory and should need no further elaboration except to say you can use any number of different free SMTP servers to do so including GMail, Hotmail and others.

8. Extra Credit: Domain redirect

Now you have a fully functional WordPress site running on Azure on the domain name http://yourchosenname.cloudapp.net. That may not be what you had in mind. Fortunately redirecting a domain to Windows Azure is very easy. There are two steps involved:

1. Use a CNAME redirect to point your existing domain to the Windows Azure domain (so www.yourdomain.com points to yourchosenname.cloudapp.net)
2. In WordPress go to Settings -> General and change WordPress address (URL) and Site address (URL) to your new domain name.

These have to be done in order and you should not change the WordPress settings until your domain fully redirects to WordPress, otherwise you won’t be able to visit your site.

Appendix: Caveats

Plugin support

Though running WordPress on Windows Azure is cool, there are some drawbacks, the most important of which is that not everything works as expected. WordPress itself will run fine, but many plugins cause weird problems or don’t work at all. This is especially true for a lot of form plugins. The reason for this is that WordPress on Azure uses SQL Azure even though WordPress is meant to run on MySQL. Needless to say this causes some rather bizarre problems not experienced elsewhere. That said this is a minor concern and one that can be resolved with some clever coding

Service resets

Due to the nature of Windows Azure, the system will sometimes reset. There is no warning when this happens and you don’t know how long it’s going to last. The way around this is to create several instances of your site. That way when one goes down the other one stays up.

Bleeding edge means weird problems

Running WordPress on Windows Azure is an interesting experience. Having created hundreds of WordPress sites on many different servers I can tell you I’ve experienced things on Windows Azure I’ve never seen before, and a lot of it I can’t explain. However most of these issues have been worked out and what we have now is a stable and solid release. Even so I must warn that by doing this you are entering into the world of extreme bleeding edge scenarios so expect the unexpected!

Good luck and report back!

Now you have the complete algorithm to get WordPress up and running on Windows Azure. The only thing left is to try it for yourself. And once you’re up, report back in the comments below and tell the world how it went, what happened and if you ran into any weirdness along the way. I’d love to hear from you and see what you’re doing so don’t be a stranger! You may also want to check out the Github forums for the scaffolding tool to see what other people are doing with this solution.