Appendix A. Creating A Local Domain Using Apache Virtual Hosts

A.1. Introduction

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.

A.2. Configuring Apache With Virtual Hosts

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.

A.3. Configuring Local HOSTS File

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 C:\Windows\System32\drivers\etc\hosts:

# 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:
#
#      102.54.94.97     rhino.acme.com          # source server
#       38.25.63.10     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.

A.4. Conclusion

In this appendix we have met how to create and enable Virtual Hosts for our local domains. There's nothing to be afraid of in here! Creating new hosts is a common and simple practice once you graduate away from trying to bundle all your projects under the default Apache document root. With a little practice you can replicate not only full domains, but also subdomains - perfectly replicating the actual hosting conditions you expect to see when the project is deployed. This enables testing of such performance enhancing tactics like hosting images, css and javascript on a collection of subdomains to get around modern browsers' simultaneous domain connections (a common bottleneck in downloading web pages) and gives you a root domain to work with rather than a more troublesome subdirectory where a root path must be prefixed to all loaded files. I'm sure you can invent any number of useful uses, and what you learn here is directly applicable on production servers where creating Virtual Hosts for your registered and hosted domains is not only common, but necessary unless you are using an intermediary management tool.

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.

Powered by jQuery Powered by Zend Framework Powered by Nginx Http Server