Getting Wordpress MU to work with subdomains on local windows machine

I’m mostly publishing this blog post for my own benefit so I don’t forget the steps I went through to accomplish the task in case I want to do it again (notes are easier to lose than blog posts). Also, while I searched around for solutions to problems I had while attempting to get things setup I had to jump around a lot. I will compile my findings and thoughts in an easy to follow manner (hopefully) for people who attempt this in the future here. I recommend you use this post in conjuction with the Wordpress MU README, and I bet both will make more sense to you.

My goal

Run Wordpress MU with unlimited subdomains locally on my windows-based laptop for development and testing purposes.

This would serve as a good substitute for the more costly hosting option of a Virtual Private Server with my hosting company (using MU with subdomains isn’t usually allowed with shared hosting plans), and also would untether me from the Internet while in development/test mode. Ultimately I do plan to buy some VPS space when/if I decide to upload any Wordpress MU solutions to Internet, but for now running it locally is all I want.

Step 1 – Install XAMPP for Windows to get your local Apache web and MySQL database server up and running and ready for local Wordpress development.

XAMPP for Windows – In short (for those that don’t know), XAMPP allows you to run an Apache server and MySQL database server (among other things) on your pc or laptop in order to have a local environment. It should be noted that this simply gives you a web and database server on your local machine and would be needed for any Wordpress install, not just MU. I already had this setup for my regular Wordpress installs for offline design and theme development.

Installing XAMPP and getting Apache and MySQL to work are pretty straightforward, but it’s beyond the scope of this post. This post from sixrevisions.com got me going when I first setup XAMPP for my Wordpress development environment. Go there first, and come back here after you get things up and running and have a regular Wordpress working without problems.

Side note: I have Windows IIS Server running on my laptop because I also do ASP.net development. I updated the “Default Web Site” in IIS to use a port other than Port 80, so that Apache could use it as that’s what XAMPP’s install expects by default. This also just made things simpler for me later on when dealing with host names and virtual servers. I was considering going back later to see if I could run Apache on a different port, but have not done so yet.

Step 2 – Satisfy Wordpress MU domain name requirements by customizing some host names

So if you already had XAMPP going, or worked through the sixrevisions post above to get a regular Wordpress dev environmnet up and running, you are ready to prepare for Wordpress MU. I would suggest that if you have already attempted the MU install script (via the index.php page) and set other values for server, site url, etc- delete all the site files from your install directory (or make a new directory all together) in order to start fresh later. Otherwise, you’ll have to fiddle with the values in your config.php and database tables later (which I wont try to cover here).

Ok, now we’re ready to make your local machine “domain name friendly” for MU. Most likely you are accessing your XAMPP apache server right now with either “http://localhost” or “http://127.0.0.1″ and it’s re-directing to the default XAMPP homepage http://localhost/xampp. Wordpress MU does NOT like IP’s addresses or the server name “localhost”, and it will say so during the install. It wants a nice clean domain name, even if it’s fabricated. So let’s start fabricating…

Go to your Windows “hosts” file. It should be located in C:\WINDOWS\system32\drivers\etc\ on both XP and Vista. However, Vista wont let you save your changes by default- see here for how to change your hosts file in Vista. We are basically going to map some names to your local machine’s IP (127.0.0.1). Add entries like so:

127.0.0.1     localhost
127.0.0.1     me.local
127.0.0.1     my-wpmu-site.local

The “localhost” entry was probably already there, but add it if not. The “me.local” entry can be called anything you want. The point is to basically create your own little domain name for your machine that is not an IP address and not a singular word like “localhost” (as that’s what Wordpress MU doesn’t like). And of course, “my-wpmu-site.local” could be anything, too. I would suggest if you decide to substitute something for “.local” you do so in both entries for consistency sake, and you don’t use the usuals like “.com” or “.net” as that may be confusing later. Save your changes, and Restart (Stop/Start) the Apache server with the XAMPP control panel (this is needed for changes you just made to take effect).

Now when you type “localhost”, “me.local”, or “your-wpmu-site.local” into a web browser, you should get the same xampp home page everytime (or whatever your apache web server’s default home page is). Our goal in the next step will be to get “my-wpmu-site.local” to redirect to the directory where you un-zipped your Wordpress MU download to in order to start the install process, while making sure “localhost” and “me.local” still go to the server’s default home.

Step 3 – Make the custom host names resolve correctly before accessing the Wordpress MU installation

Make sure you’ve downloaded and un-zipped the latest version of Wordpress MU to the directory you want your site to reside- I used “C:\xampp\htdocs\my-wpmu-site\”. Now you have to get to that directory in a web browser. In order to use nice looking subdomains, we don’t want to specify it like this “localhost\my-wpmu-site”- that would have defeated the whole purpose of Step 2! Plus, the install page will warn against it. It’s also important to note here that if you haven’t tried and failed already, Wordpress MU is not like regular Wordpress in that you CANNOT manually edit wp-config and be up and running- if only it were that easy!

So let’s start working with some VirtualHosts and get our domains pointing to where we want them. Locate the following files:

C:\xampp\apache\conf\httpd.conf
C:\xampp\apache\conf\extra\httpd-vhosts.conf

These are configuration files for your Apache web server. This site will tell you all you would ever want to know about configuring apache, but for our purpose just remember these couple things- Apache reads these files from the top down, httpd is accessed first, httpd-vhosts should be referenced by httpd toward the bottom, and anything in httpd-vhosts could be moved into httpd (but are separated in XAMPP’s Apache install for clarity’s sake by default).

First, open httpd.conf with Notepad and make sure of some things.

Search for “LoadModule rewrite_module modules/mod_rewrite.so” and make sure it is uncommented (no “#” symbol at the beginning of the line). This turns on the famed “mod_rewrite” option which is required for “pretty url’s” in Wordpress. If you have a previous Wordpress install working with “pretty url’s” already, then you will find that you are all set.

Search further down the file for “httpd-vhosts” and make sure the line that says “Include conf/extra/httpd-vhosts.conf” is also uncommented. This is our very important “link” to the httpd-vhosts.conf file.

Some other things to verify-
> ServerName is “localhost” or your machine’s name
> DocumentRoot is “C:/xampp/htdocs”
> “AllowOverride FileInfo Options” specified in the first “<Directory />” tag instead of “AllowOverride None” (You will probably notice that “AllowOverride All” is set for the “<Directory “c:\xampp\htdoc” />” tag that immediately follows- this is ok).

Save any changes you may have made to httpd.conf and close it.

Next, open httpd-vhosts.conf with Notepad and make the changes necessary to get the host names we made in Step 2 to resolve correctly. There will be a lot of information telling you what to do, and it should all be commented out and therefore not in use (remember, “#” = not in use). The stuff actually being used in my httpd-vhosts file looks like this:

NameVirtualHost *:80

<VirtualHost *:80>
DocumentRoot c:\xampp\htdocs\my-wpmu-site
ServerName my-wpmu-site.local
ServerAlias *.my-wpmu-site.local
</VirtualHost>

<VirtualHost *:80>
DocumentRoot c:\xampp\htdocs
ServerName localhost
ServerAlias *.local
</VirtualHost>

To the best of my understanding, what this basically is saying is for all requests coming over Port 80, try to match the hostname (set back in Step 2) with the ServerName or ServerAlias in the VirtualHost directive. I’ve found that again this works from top down, and it’s going to take the first match it finds. Therefore, put the most specific ones first! I found this out the hard way. For a while I had the “localhost” one listed first, and since I have “*.local” specified as a ServerAlias whenver I’d type “my-wpmu-site.local” into a browser, it would match the “*.local” alias (because “*” is a wildcard) and still go to the default location “xampp\htdocs” instead of my Wordpress MU directory “xampp\htdocs\my-wpmu-site”. Putting them in the order seen above finally cured that problem.

So, at last, browsing to “my-wpmu-site.local” should resolve to the elusive Wordpress MU installation screen. If it doesn’t for you, I’m not sure what to say other than to go back through everything to this point and see if you missed something along the way.

Step 4 – The Wordpress MU installation

Now that you are on the Wordpress MU installation page with a nice looking URL like “http://my-wpmu-site.local” you are probably feeling pretty good. I know I sure did when I finally got there! Don’t go crazy now- just make sure “Sub-domains” is selected (that is why we went through most of this trouble after all), and you specify an EMPTY DATABASE with a user that has proper credentials. Notice the “Server Address” box matches the nice domain we’ve gone through so much trouble to create- don’t change it! With everything done to this point, this part should be a breeze and if you have any familiarity with regular Wordpress you know now to log-in with the automatically generated password only to change it immediately to something you’ll remember.

Step 5 – Making child blogs and sub-domains to love them

Ok, so you might as well leave “Allow New Registrations” disabled, or disable it (Site Admin – Options) if it’s not already. For one, this is your local machine so you’re not going to have a bunch of people visiting your local MU site wanting their own blog. Second, and this is the one difference that having your MU site up on the Internet with a web host with a real DNS server, there’s no automatic way (that I know of) to resolve sub-domains using the Windows hosts file. This is because while the “*” wildcard character can be used in the httpd-vhosts file, wildcard characters don’t work the same way in the hosts file.

For example, it would be nice to be able to put the following entry in the hosts file and call it good:

127.0.0.1     *.my-wpmu-site.local

But, it just doesn’t work (trust me, I tried).  Consequently, for each child blog you create in Site Admin, you have to add a matching entry in your hosts file. So if you create child blogs “Blog1″, “Blog2″ and “Blog3″ for your “my-wpmu-site”, all of the following entries must be added to your hosts file:

127.0.0.1     blog1.my-wpmu-site.local
127.0.0.1     blog2.my-wpmu-site.local
127.0.0.1     blog3.my-wpmu-site.local

The good news is the same is NOT true for your httpd-vhosts file. The “*” wildcard in the “ServerAlias *.my-wpmu-site.local” portion of the <VirtualHost /> directive handles things, and then the Wordpress MU engine takes over from there and directs the sub-domain request to the appropriate child blog.

Step 6 (Optional) – Handle multiple Wordpress MU’s

You have laid the groundwork for a sleek Wordpress MU development environment, it would be a shame to stop with one. I think you have the idea on how to accomplish it, but just in case here are the steps:

1. Create a new directory (eg: “\xampp\htdocs\my-new-wpmu-site”) and unzip the files from your wordpress-mu download again (starting fresh is important)
2. Create a new empty database on your MySQL server
3. Decide on your new WPMU site name (eg: my-new-wpmu-site)
4. Add an entry in your hosts file for this new site (eg: 127.0.0.1    my-new-wpmu-site.local)
5. Add a matching entry in your httpd-vhosts file, and make sure to place it above the one you have for “localhost”. This entry will look exactly like the one you created for “my-wpmu-site” except it will say “my-new-wpmu-site”.
6. And so on…

—

Well, that’s all for now. I hope I’ve helped you if you’ve happened upon this blog post.