Table of Contents
During your programming career, or hobby, you'll eventually need to learn how to use Virtual Hosts. The concept refers to hosting multiple domain names at the same local IP. These domains are configured for your web server, and although the name may differ, we'll use the Apache terminology for consistency.
In this appendix, I'll describe how to create a local domain called "helloworld.tld" whose URL will be http://helloworld.tld. The principle is almost identical for public domains, the main difference being public domains rely on configuring your DNS records to host the new domain name. For local domains, however, rather than using DNS records we can simply add the new domain to your system's hosts file which is available for nearly all systems, including Windows.
The reason we use local domains in development is fairly simple. It lets us create new domains for each project and removes the need to maintain everything as a set of subdirectories under localhost. It's also a really simple task once you run through it once since it doesn't vary from domain to domain other than the server name and the server specific Directory or Location configurations you may wish to employ.
To create a new local domain, you need to start by configuring Apache. How this is accomplished for Virtual Hosts varies between systems, so the following assumes a Ubuntu system with some alternative notes including Windows instructions.
Ubuntu employs a managed setup for Apache Virtual Hosts and modules which is quite a handy way of configuration. Virtual Hosts are defined in files located in /etc/apache2/sites-available using any filename (though obviously a name related to the domain to host is preferable - I just use the domain name itself most of the time). While splitting out configuration among numerous files allows for better atomic control, many other systems will generally just use either the main http.conf or apache2.conf file, or some Virtual Host specific file such as http-vhosts.conf.
The basic Virtual Host configuration we're seeking is as follows:
# Setup Listening Port NameVirtualHost *:80 # Ensure "localhost" is preserved unchanged pointed # to the default document root for our system. <VirtualHost *:80> ServerName localhost DocumentRoot /var/www </VirtualHost> # Setup "helloworld.tld" Virtual Host <VirtualHost *:80> ServerName helloworld.tld DocumentRoot /home/padraic/www/helloworld/public <Directory /home/padraic/www/helloworld/public> Options Indexes FollowSymLinks Includes AllowOverride All Order allow,deny Allow from all </Directory> </VirtualHost>
With Ubuntu, we would implement this configuration by first editing /etc/apache2/ports.conf to contain:
# Setup Listening Port NameVirtualHost *:80
Since Ubuntu has localhost predefined with a Document Root of /var/www in a configuration at /etc/apache2/sites-available/default, we only need to create a new file to contain the helloworld.tld configuration at /etc/apache2/sites-available/helloworld.tld containing:
# Setup "helloworld.tld" Virtual Host <VirtualHost *:80> ServerName helloworld.tld DocumentRoot /home/padraic/www/helloworld/public <Directory /home/padraic/www/helloworld/public> Options Indexes FollowSymLinks Includes AllowOverride All Order allow,deny Allow from all </Directory> </VirtualHost>
In Windows, under XAMPP for example, you would edit C:/xampp/apache/conf/extra/http-vhosts.conf since there are no separate ports or domain specific conf files. To ensure the vhosts file is loaded as a configuration, the main XAMPP http.conf file should include a line containing:
# Virtual hosts Include conf/extra/httpd-vhosts.conf
Here's a sample configuration under XAMPP for Windows:
# Setup Listening Port NameVirtualHost *:80 # Ensure "localhost" is preserved <VirtualHost *:80> ServerName localhost DocumentRoot "C:\xampp\htdocs" </VirtualHost> # Setup "helloworld" Virtual Host <VirtualHost *:80> ServerName helloworld.tld DocumentRoot "C:\projects\helloworld\public" <Directory "C:\projects\helloworld\public"> Options Indexes FollowSymLinks Includes AllowOverride All Order allow,deny Allow from all </Directory> </VirtualHost>
Any other Windows variation will follow a similar pattern. If you get stuck, simply add the configuration at the end of the main Apache configuration file.
The overall configuration above creates two domain names: localhost and helloworld.tld. Recreating localhost seems a bit silly, but it's a necessity to ensure localhost remains intact and usable as a unique domain name recognised by Apache when employing Virtual Hosts. The section after localhost configuration creates a new Virtual Host with a server name of "helloworld.tld" which should point Apache to the new Document Root whenever we enter http://helloworld.tld into a browser. Since we are using the Zend Framework, the Document Root is always the /public directory of the application. Also note, the application can be stored almost anywhere which leaves you a lot more flexibility on where to store application files. You could just use a /www or /public_html directory in your home directory on Linux, or a /www directory in your Windows C drive. Actually, this directory's name is unimportant - merely a handy convention so you know what it is. Feel free to call it wheelsoffire if you want.
The final part is to add a Directory configuration for the new Virtual Host's Document Root. This ensures Apache can serve requests from this directory by supplying appropriate permissions. Apache will not serve files from a directory without the correct access permissions. By default, options are severely limited to prevent unauthorised access from the web, so be sure to add this to allow files to be served from the Document Root. The options I'm using here are the usual ones Apache applies to localhost's Document Root which are fairly liberal and allow for the use of .htaccess files so users can access Apache configuration options at runtime.
To activate this Virtual Host under Ubuntu we need only run the following commands to create a symlink for the new configuration file at /etc/apache2/sites-enabled/helloworld.tld:
sudo a2ensite helloworld.tld sudo /etc/init.d/apache2 reload
If you are on Windows or another Linux variant, reloading or restarting Apache has the same effect since you likely won't be using the Ubuntu site layout for these systems. The Ubuntu method ensures you can take a domain offline using the opposite a2dissite command.
There are similar commands like a2enmod and a2dismod for enabling/disabling modules more easily than manually editing configuration files.
We're not done quite yet however. There is also the matter of mapping the new domain "helloworld" to the correct local IP. This is easily resolved by adding the new domain name to the local HOSTS file which recognises and maps local domains to IP addresses.
Under Ubuntu, the file is located at /etc/hosts and you can edit it using something like:
sudo nano /etc/hosts
We can ensure our system recognises the local domain we want to use for the new Virtual Host configuration by editing this to something like:
127.0.0.1 localhost 127.0.0.1 helloworld.tld 127.0.1.1 padraic-desktop # The following lines are desirable for IPv6 capable hosts ::1 ip6-localhost ip6-loopback fe00::0 ip6-localnet ff00::0 ip6-mcastprefix ff02::1 ip6-allnodes ff02::2 ip6-allrouters ff02::3 ip6-allhosts
Nothing else is needed -
just the association of our local domain to the localhost IP address.
Under Windows, you should be aware this file is generally only editable by
an Administrator user, so on Windows Vista you may need to adjust
permissions temporarily or open an editor with Administrator privileges in
order to edit this. Otherwise the editing is almost identical and you can
find the HOSTS file at
# Copyright (c) 1993-2006 Microsoft Corp. # # This is a sample HOSTS file used by Microsoft TCP/IP for Windows. # # This file contains the mappings of IP addresses to host names. Each # entry should be kept on an individual line. The IP address should # be placed in the first column followed by the corresponding host name. # The IP address and the host name should be separated by at least one # space. # # Additionally, comments (such as these) may be inserted on individual # lines or following the machine name denoted by a '#' symbol. # # For example: # # 184.108.40.206 rhino.acme.com # source server # 220.127.116.11 x.acme.com # x client host 127.0.0.1 localhost 127.0.0.1 helloworld.tld ::1 localhost
In both variants, we see that helloworld.tld maps to 127.0.0.1 (the same IP as localhost but Apache will note the difference and use the correct Virtual Host we've configured). Don't worry about the ::1 reference found here, it's an IPv6 pattern we don't need to touch at this time. I suggest reading more about the HOSTS file to understand any other options fully like using differing local IPs.
Throughout the book, we'll refer to other configuration options you can add to your Virtual Host settings since I only touched the absolute essentials here.