Setting up subdomains in virtual hosts on your local machine

 
 
 

I recently built a 'software as a service' web application which allowed clients to signup and create webpages online and setup unique short url links to direct and track traffic. Each client had a subdomain off of the main domain which routed traffic to the correct webpage, we also recorded information about the visitor and displayed real-time statistics within an admin area accessible via a directory off of the clients subdomain.

One of the issues I hit early on in this project was how to build this on my local machine, my setup used an Apache server on my Mac with a port based directory (such as http://127.0.0.1:9000) which would not play nicely with subdomains. Luckily with the beauty and simplicity of the Apache server I was able to setup development domains locally and create a wildcard virtual host to catch all my subdomains.

Unfortunately this does need some technical knowhow, we are going to use command line with vim. If you don't know how to use these tools then check out some resources or set your Mac or PC to show all files and browse to files directly.

Setting up development domains

Before setting up our subdomains we need to create our main development domain, we are going to need to edit the apache host file if you have show all files on you can browse to the file direct at this location /private/etc/hosts or you can use the below command on your command line to open the file in vim:


# sudo vi /private/etc/hosts
enter your password if requested

Now you are in vim preform the following commands to insert into the file:


# i

You may have entries in the file already, using your arrow key scroll to the bottom of the file and add the following (replace domain with whatever you want to call the domain):


127.0.0.1    domain.dev

To close and save perform the following:


press esc
# :w
# :q
press enter if requested

Its important that the extension (TDL) of the domain remains .dev, if you add .com or a any other real TDL you will find that you can't access the real site anymore, this is because the purpose of this statement is to point the traffic to domain locally to your local apache server. If you enter a real domain here you will point that to your local machine and that could end in plenty of confusion. I always add .dev to my development domains so its nice and easy to keep track of and will remind you that you are on the development domain.

Add your subdomains

Now we are pointing the domain to the local machine we can add all of our subdomains, this done within the same file. So we will open and edit it in the same way:


# sudo vi /private/etc/hosts
# i

Add the following for all your subdomains


127.0.0.1    subdomain1.domain.dev
127.0.0.1    subdomain2.domain.dev

Close and save


press esc
# :w
# :q
press enter if requested

Now we have our domain set up locally with subdomains and pointing them to our local apache server. Reboot your apache server to see the changes:


# sudo apachectl restart

enter your password (if you don't have one just press enter)

Open a browse and you should see your local default apache page.

Setting up your Virtual Host Environment

Great so we have our domains but they are pointing to the default apache page, how do we point these to our web application? Well apache provide us with a virtual host facility which will pick up the traffic and point it where we want it. Let add the virtual hosts:


# sudo vi /private/etx/apache2/extra/http-vhosts.conf

Add the following to the bottom of your file (edit the DocumentRoot and Directory to where your web application is stored):



 ServerName domain.dev
 ServerAlias domain.dev
    DocumentRoot "/Users/your-name/Sites/website/httpdocs"

    
      AllowOverride All
      Options All
      Allow from all
    


This will grab all that local traffic to domain.dev and point it to your web application. Next we will add our wildcard virtual host in the same file:



 ServerName domain.dev
 ServerAlias *.domain.dev
    DocumentRoot "/Users/your-name/Sites/website/httpdocs"

    
      AllowOverride All
      Options All
      Allow from all
    



press esc
# :w
# :q
press enter if requested

The star in front of the domain indicates a wildcard and will pick up all subdomains and point it the same web application. If you wanted you could point a subdomain to different files by editing the virtual host and replacing the * with the subdomain and changing the DocumentRoot and Directory to the different files.

Whats next

Now we have all our subdomains and main domain pointing to the same site, I won't go into to much detail on my particular setup as everyones will be different but we could lookup the client based on the subdomain and route the traffic accordingly.