Setting Up A Subdomain on Localhost

December 21st, 2007 | by: Team Offshoot

Setting up a development server on your local machine is a great way to make sure that stuff works before it goes live, but it’s also especially good when working in a subversion / team environment.

Each member can run a local copy of Apache (using XAMPP, for example) on their box and not have to worry about other people overwriting their business. And if you are working in a subversioned environment, then just do a commit when whatever you’re working on is in a stable state.

But one of the obvious problems with this setup, especially when working on multiple sites at the same time, is that you end up with a lot of subdirectories referencing your local copy of the live server’s web files (like http://localhost/offshootinc.com/) — and that sucks. And it seems like you’re always going to run into path problems.

Getting something more like the live server seemed to be the way to go: http://offshootinc.com.localhost/

If the team standardizes the use of relative-to-root path naming (that is, use <a href=”/link.html”> instead of <a href=”http://offshootinc.com/link.html”>), then you get the convenient situation of being able to interchange files rather seamlessly between the local development server and the live version.

Anyway, the steps!

So, I’m going to assume that you’ve got Apache up and running. It seems like the steps should be more or less the same for more than just Windows machines, just the paths to the various config files would be different.

The example paths I’m going to be using are assuming that you’ve installed XAMPP, using the default install paths.

The first thing you need to do is create a subdirectory in the web root of your Apache server. The default directory is “c:\xampp\htdocs”.

For this example, I’m going to use sub.domain.com (the path would be “c:\xampp\htdocs\sub.domain.com”).

Edit Apache Config

In one of the Apache config files, you’re going to be setting up a “virtual host”.

The config file that you need to track down will probably depend on your setup, but for the default XAMPP installation, this file will be located at “c:\xampp\apache\conf\extra\httpd-vhosts.conf” (although I think that you can pretty much put it in any config file that gets loaded).

Add the following, if it doesn’t exist already.

<VirtualHost 127.0.0.1:8080>
DocumentRoot C:/xampp/htdocs/
ServerName localhost
ServerAdmin admin@localhost
</VirtualHost>

Then add the following to have “c:\xampp\htdocs\sub.domain.com\” point to http://sub.domain.com.localhost/:

<VirtualHost sub.domain.com.localhost>
DocumentRoot C:/xampp/htdocs/sub.domain.com/
ServerName sub.domain.com.localhost
ServerAdmin admin@sub.domain.com.localhost
<Directory “C:/xampp/htdocs/sub.domain.com.localhost/”>
Options Indexes FollowSymLinks
AllowOverride FileInfo
Order allow,deny
Allow from all
</Directory>
</VirtualHost>

To learn more about the configuration options for virtual hosts, check out the Apache documentation on the subject.

Edit HOSTS File

Before your computer uses the Internet’s DNS servers to lookup the IP address of a particular domain name, it first checks its own HOSTS file.

Your HOSTS file lets you map custom domain names to a certain IP address. In our case, we’re just going to map the custom subdomain that we setup to our localhost (127.0.0.1).

On a Windows XP machine (and I believe on Windows Vista), you can find your HOSTS file in the “C:\Windows\System32\drivers\etc” directory. Windows 2000, it’s ” c:\winnt\system32\drivers\etc\hosts”. And on Linux, it’s just “/etc/hosts”.

Open it up in a text editor, and add the following lines:

127.0.0.1 sub.domain.com.localhost

Reboot!

That’s it!

Fire up your browser, and go to http://sub.domain.com.localhost/ and you should be good to go.

Digg it!

25 Responses to “Setting Up A Subdomain on Localhost”

Chris Woodford said:

February 5th, 2008 at 11:40 am

in the httpd-vhost.conf file, you want to make sure that the NameVirtualHost is set to something like this:

#
# Use name-based virtual hosting.
#
NameVirtualHost 127.0.0.1:8080

The Apache documentation says:

“Name-based virtual hosting is usually simpler, since you need only configure your DNS server to map each hostname to the correct IP address and then configure the Apache HTTP Server to recognize the different hostnames.”

Running subdomains on localhost would all be using the same IP address, i.e. 127.0.0.1, so it seems that Name-based virtual hosting should be used.

michael said:

March 5th, 2008 at 3:07 pm

great post. real concise and simply.
got me testing all sorts of sites quickly and cleaned up my code by keeping this mess out of it.

Nels said:

March 15th, 2008 at 6:21 pm

Doesn’t work. Apache Server fails to start.

Pretty vague directions for a newbe. Do you need an entry for every folder in htdocs you set up? What does :8080 mean? Do the sub directories go under htdocs or in sub.domain.com?

Ed said:

March 31st, 2008 at 4:50 pm

One thing to note: Apache does not like the styled double quotes, which is going to be a problem if you cut-and-paste the example above. When you edit your httpd-vhosts.conf, replace the double quotes with typed-in quotation marks.

Will said:

May 2nd, 2008 at 11:46 am

Brilliant, thanks. I’ve been working with Apache for a while, and I don’t know why I didn’t think of this earlier. Developing multiple sites on my local machine will be so much easier :)

Will said:

May 2nd, 2008 at 11:47 am

P.S. There is no reason why this has to be a “xxx.localhost” domain. I’ve set up regular “domain.com” domains to do exactly the same thing.

Danny N said:

July 17th, 2008 at 3:03 pm

Good stuff mate!
The only thing I had to change was the quotes for single quotes (‘).
I didn’t quite understood Chris’ first post, but went fine with the config given by the article.
Thanks for the help. Hopefully I’ll be able to help others in the future :)
cheers!
Dan

Jonah Dempcy said:

July 25th, 2008 at 12:09 am

I had to uncomment this line:

NameVirtualHost *:80

Also I checked the docs and used the example from there, since I couldn’t get your example working for some reason. (?)

This is what worked for me:

ServerName localhost
DocumentRoot C:/xampp/htdocs/

ServerName mysite
DocumentRoot J:/xampp/htdocs/mysite/

And then adding the line to c:\windows\system32\drivers\etc\hosts …

127.0.0.1 mysite

Now I just type ‘mysite’ into the browser to view it. (this could be yoursite.com.localhost or whatever you prefer to call it).

Thanks for the example, not sure what I did wrong but it pointed me in the right direction to the Apache docs and I got it sorted out pretty quickly …

Chris said:

July 25th, 2008 at 10:13 am

It seems that depending on your install of apache, the NameVirtualHost line may be commented out by default. I believe it should be uncommented in order for this to work correctly. At least when you get the point where you have multiple lines in your hosts file all mapping to your local IP.

Joe Critchley said:

August 2nd, 2008 at 8:53 am

The element needs to use standard double-quotes, instead of left and right quotes. Otherwise, Apache may fail to start.

Great post, thanks.

Samiul said:

October 19th, 2008 at 10:29 pm

Thanks! Its help me. :)

James Rintamaki said:

April 11th, 2009 at 7:04 am

thanks for info Team Offshoot! I’ve got the subdomain working now in my xampp installation, however, now when I change all my paths to reference the root “\path\to\files” (as opposed to “path\to\files”), I am getting a php include / perl issue and I can’t seem to figure out why:

Warning: include_once(\header.php) [function.include-once]: failed to open stream: No such file or directory in C:\users\maki\docs\xampplite\htdocs\spiffycake\index.php on line 2

Warning: include_once() [function.include]: Failed opening ‘\header.php’ for inclusion (include_path=’.;C:\users\maki\docs\xampplite\php\pear\’) in C:\users\maki\docs\xampplite\htdocs\spiffycake\index.php on line 2

I have verified that “C:\users\maki\docs\xampplite\php\pear\” does indeed exist, but no matter what I try, path’ing from the root never works :-\ – any suggestions?

Giussepi said:

August 24th, 2009 at 8:10 pm

Very usefull information!!!

Thanks :)

Nico said:

September 10th, 2009 at 2:56 am

I searched ages for that file @ C:\Windows\System32\drivers\etc
Thank you ! :D

Magix said:

October 11th, 2009 at 11:20 pm

When I go to try and save the HOSTS file, it says “Access denied. Make sure it isn’t open in another program.” What do I do?

iwanttobelieve said:

October 15th, 2009 at 7:20 am

This is particularly useful for testing locally. But I would like to ask about subdomain and folder, which one is better?

Thanks :)

Joe said:

October 24th, 2009 at 12:13 am

Now that virtualhost is set in those files, why can’t I see htdocs, when I type in http://localhost/

Joe said:

October 24th, 2009 at 1:05 am

Check it:
In httpd-vhost.conf file…

# Use name-based virtual hosting.
NameVirtualHost *:80

DocumentRoot C:/xampp/htdocs/
ServerName localhost
ServerAdmin admin@localhost

DocumentRoot C:/xampp/htdocs/subdomain/
ServerName subdomain.localhost
ServerAdmin admin@subdomain.localhost

Options Indexes FollowSymLinks
AllowOverride FileInfo
Order allow,deny
Allow from all

Unh!…

And in your HOSTS file:
127.0.0.1 subdomain.localhost

Make it simple.

Ben said:

October 27th, 2009 at 3:42 pm

If you are copying and pasting, remember to re-do the quote marks in the example above – as they will stop apache from restarting!! “From curly to normal”

Chris M said:

November 13th, 2009 at 6:39 pm

I can’t get it working either. I followed the steps carefully but now i get a “server not found” message.

Regan Rajan said:

December 22nd, 2009 at 6:48 am

Its true that the advise above did not work. It is mainly because of the NameVirtualHost. I found a much simple one here: http://www.ardamis.com/2005/08/11/xampp-apache-namevirtualhost/

The suggestion was simple and worked. Just add like this in C:\xampp\apache\conf\extra\httpd-vhosts.conf;

NameVirtualHost *:80

DocumentRoot “C:/xampp/htdocs”
ServerName localhost

DocumentRoot “C:/xampp/htdocs/sub”
ServerName sub.localhost

And add this in the C:\Windows\System32\drivers\etc\hosts
127.0.0.1 localhost
127.0.0.1 sub.localhost

Regan Rajan said:

December 22nd, 2009 at 7:07 am

Ops, the server is stripping off the tag. You need to have the “Less than” and “Greater than”.

I try to write again using html encoding;

NameVirtualHost *:80
<virtualhost>
DocumentRoot “C:/xampp/htdocs”
ServerName localhost
</virtualhost>
<virtualhost>
DocumentRoot “C:/xampp/htdocs/sub”
ServerName sub.localhost
</virtualhost>

If that also come out without the tags then maybe you can take a look at the blog post which I published: http://reganrajan.blogspot.com/2009/12/how-to-add-subdomainslocalhost-if-using.html

Ben J Walker said:

December 28th, 2009 at 5:26 am

Works fine for me until I add a second subdomain, which for some reason points back to the first one I set up. Any ideas?

passcod said:

January 28th, 2010 at 8:19 pm

Note that you don’t need to reboot (on a windows machine) :

All you have to do is stop then start (restart) Apache, and then unplug / switch off any network cable / wifi … and then restart them. And depending on what file you change, you only need to restart one of these: Apache for the .conf files, and the network for the hosts file.

Usually this is faster than rebooting. I’ve only tested that on Windows (xp / vista / 7), but I’m sure it can be done on something else too…

diju said:

April 11th, 2010 at 6:51 am

i have created a domain and a subdomain but when ever i enter the subdomain , the page loads from domain. am using linux .Please tell me all the configuration needed.

Post a Comment:

*
To prove that you're not a bot, enter this code
Anti-Spam Image