Blissful Testing of Locally Hosted Sites

When I first started using a web server on my local machine for development, I used to create a separate virtual host for every site I worked on. Then I learned that you can use a ServerAlias with a wildcard to handle multiple sites with a single virtual host. Since then, I’ve been using the following simple configuration to test most of my projects:

	ServerAlias *
	VirtualDocumentRoot /path/to/projects/%1
		AllowOverride All

This tells Apache that any domain ending with should be served by the directory in /path/to/projects/ that has the same name as the beginning of the domain. For example, would be served from /path/to/projects/foo/. This reduces my per-project setup to just adding an entry in /etc/hosts to map the custom domain to my local machine, e.g., Unfortunately, wildcards can’t be used in the hosts file, so this step needs to occur for every project. That’s a little annoying, but it’s easy enough that I was willing to live with it.

As I started working on more sites (as opposed to libraries or frameworks that happen to need a web server), I created another VirtualHost to create nicer domains and handle subdomains. If I’m working on, I create a directory named / in my projects directory and use the domain for testing.

	ServerName local-dev
	ServerAlias local-dev.*
	VirtualDocumentRoot /path/to/projects/%2+
		AllowOverride All

Using %2+ tells Apache to use every part of the domain after the first part. You can read more about how the VirtualDocumentRoot interpolation works in the mode_vhost_alias documentation. And of course, I would add to my hosts file.

Testing from physical devices

Unfortunately, there is a big limitation to this setup. When testing from a physical device, such as a phone or tablet, the custom domain won’t map to your local web server. Since the physical device doesn’t know anything about the hosts file on the machine with the web server, trying to load from the device’s browser isn’t going to work. This generally discouraged me from testing on physical devices because I never had a great solution to this problem. Whenever the need would arise, I’d create another virtual host using my machine’s LAN IP and a random port:

	DocumentRoot /path/to/projects/
		AllowOverride All

Then I can connect to instead of from any physical device connected to my network. But I’ve lost the benefit of the wildcard aliasing and now I need to remember which port to use. This can be quite burdensome as the number of sites increases, especially since each site needs to use a different port.

After years of dealing with this, I decided to ask for help on Twitter. I got a few responses, but the one I like the best came from Andrew Sheppard, who pointed me to to the rescue is a free service from 37signals, which provides wildcard DNS for any IP address. Just like we can map * to the appropriate directory on our local machine, can map * to the appropriate IP for local testing. The URL structure is nice and simple, just prepend the IP address you want the domain to resolve to; the DNS server handles the rest. In this case, we’d use to map the domain to

This solves the DNS issue and removes the need to edit the hosts file for each site. But given a domain of, we still don’t know which directory to server the site from. To address this, allows adding as many subdomains as you want. So we can use and then create a virtual host that knows how to handle domains.

	ServerName xip
	ServerAlias *
	VirtualDocumentRoot /path/to/projects/%-7+
		AllowOverride All

Handling DNS on your local machine

Although the setup does allow for zero-configuration setup, there are a few caveats.

The URLs are long and a bit ugly. I’ve created a simple page,, to generate the URLs so I don’t need to type the full URL in the tiny address bar on my devices. I also kept my local-dev.* virtual host enabled so that I can use shorter, nicer URLs if I want, though this does require adding an entry in the hosts file as mentioned above, and doesn’t allow testing from physical devices.

The URLs don’t work offline. Obviously if you can’t can’t connect to, the whole thing is going to fall apart.

The URLs aren’t shareable. Since the domain contains your personal LAN IP, sharing links with other developers working on the same site from their local machine won’t work (unless you happen to have the same LAN IP). However, it’s quite easy for the other person to change the IP after you’ve shared it with them.

More on link sharing

Link sharing is really useful when working on a project with other people, so it’s worth discussing specifically. As I mentioned above, while URLs can’t just be copy/pasted, they’re fairly easy to work with. However, having a common setup, such as local-dev.* for your projects makes link sharing much easier. If everyone working on the project is using when testing from the main machine, then link sharing just works.

To avoid having everyone edit their hosts file to get the domain mapping to work, another option is to actually create a DNS record for By creating an A record that points to, you can get back to a zero-configuration setup. However, you do have the same offline problem as using, but that can be solved via the hosts file for any developer that needs offline access to work.

Other solutions

As with most things related to software development, there’s more than one solution to this problem. Matt Surabian wrote an article about using Charles Proxy to test local sites with physical devices in response to my tweet. Using Charles Proxy has a different set of pros and cons, so I suggest reading Matt’s article and determining which solution works best for you.