Running Apache on Ubuntu Linux with SSI

When developing your own website, you frequently write your HTML and CSS locally to make sure everything looks good before uploading it to your web host. Many times, however, you will find that you have a lot of elements that end up duplicated across every page in the site. For this site, that would include components like the page header and footer, navigation, and sidebar.

Server-Side Includes (SSI) can be used to reduce this duplication. This is especially useful if you ever decide to make changes to the common components on the site since you won't have to modify every page to make the change. This power comes at a cost however. Once you start using Server-Side Includes, you will need to have a web server to render the pages if you want to look at the site as it will appear on the web. Now, before you rush off into SSI glory, you might want to check with your hosting provider to make sure they support it - if they don't then obviously Server Side Includes aren't the solution you're looking for.

The most commonly used web server (and likely the one used by your web hosting provder) is Apache. Apache can run on Windows, but most web hosts are likely running it under Linux and (for reasons I'll discuss later) you probably should to if you want to use SSI. Linux used to be a challenge to get up and running, but today it's dead simple (insofar as installing any operating system is simple).

Pick Your Approach

There are a couple different ways to proceed if you want to run Apache on Linux. If you have some older hardware you don't mind parting with, that's one way to go. The other way is to run Linux in a virtual machine. The remainder of this tutorial assumes that we're going with the latter option. Installing Linux on physical hardware will require some extra steps to get your web content uploaded to Apache. While that's fairly straightforward, it isn't something we're covering here. Instructions on installing Xubuntu Linux in a virtual machine using VirtualBox can be found here.

Install Apache

Once you have Linux up and running, it's time to install the Apache Web Server (assuming you didn't pick a Linux distribution that has it pre-installed). This can be done using the system Package Manager or from the command line. For me, the command line is the only way to fly. Besides that, some of the later steps require the command line, so we might as well start using it now.

Open a Linux Terminal from your applications menu (in Xubuntu, this can be found in Applications > Accessories > Terminal). Now type the following:
sudo apt-get install apache2
The system should prompt you for your root password that you set up when you installed Linux. If you only have a single user set-up, odds are your account is root. Congratulations, but remember that with great power comes the ability to screw things up dramatically.

Project Directory

Now that Apache is installed, you might find it useful to create a new project directory for your website. This is especially true if you plan on working on multiple sites. There are multiple ways to add a project directory for your site, we're going to use one in your home directory. In your terminal window, type the following:
mkdir mysite
Where 'mysite' is replaced with whatever you'd like your directory to be called. The remainder of this tutorial uses 'mysite'. Make sure you change the references in the remainder of the commands.

Enable mod_include

Now we turn on mod_include so that we can leverage Server-Side- Includes. Locate the apache2 install directory. You will most likely find this in /etc/apache2.
cd /etc/apache2
Now, we could enable mod_include by linking to it from the the mods-enabled subdirectory. I've done it this way and it works, but there is an apache command to do this.
sudo a2enmod include

Configure Your Local Site

Now it's time to create your site configuration. Apache provides a default configuration to work with that you can copy. In the Apache 2 folder, execute the following.
sudo cp sites-available/default sites-available/mysite

Next, we edit the configuration we just created to point to the mysite folder you created earlier. This is where we also turn on Server-Side-Includes. This example will use the 'pico' terminal editor (which is easier than some of the editing options in Linux). If you know 'vi' you can use that as well.
cd .. sudo pico sites-available/mysite

Now we have a copy of the default configuration file open where we need to make the following edits (you'll need to replace 'user' in the settings below with your username and also change the 'mysite' directory name if necessary):

            
<VirtualHost *>
  ServerName localhost
  ServerAlias localhost
  DocumentRoot /home/user/mysite

  <Directory /home/user/mysite>
    Options IncludesNoExec Indexes FollowSymLinks MultiViews
    Order allow,deny
    allow from all
    AddHandler server-parsed .html
  </Directory>
  
  ...

Once you've entered that, press Ctrl+O then Ctrl+X to exit pico.

Note: There are two ways to do Server-Side-Includes. One is to use the AddHandler method above. The other is called XBitHack. To use the latter, replace the AddHandler line above with
XBitHack On
XBitHack looks at the executable bit for the files that Apache serves up. If the executable bit is set, the file will be processed for Server-Side-Includes. To me, this is a better solution, but many web hosts don't support XBitHack.

Also Note: By using the AddHandler line as we have above, we are forcing Apache to inspect every .html file it serves up for include directives. If many of your files don't use SSI, this is not what you want to do. Instead use the following:
AddHandler server-parsed .shtml
Now you have a different problem, all of the files you want to use Includes in will need to have a different file extension. This is a trade-off. I went with the .html option since nearly every page uses Includes.

Enable Your Site

Now that there is a configuration for your local site, it's time to enable it within apache and disable the default site. Here are the respective commands to do just that.
sudo a2dissite default sudo a2ensite mysite

Populate the Project Directory

If you already have some web pages that you're working with, you'll need to move those to the mysite directory in your home folder. If not you'll need to create a bare-bones index.html file inside the 'mysite' folder.

Restart Apache

To enable the configuration changes we made and get Apache to start processing include directives, we need to restart the web server. Return to your terminal and enter the following at the command line (and enter your password when prompted):
sudo /usr/sbin/apache2ctl restart
Assuming everything is set up correctly, that should be the last sudo command you have to issue.

Add Include Directives

Now that we've got everything set up, we can start adding include directives to our .html (or .shtml) files. For any HTML that you have repeated across multiple pages, extract the section in question and save it to another .html file. If you have multiple sections, you may want to create an 'includes' directory in your project directory. Common components include headers, footers, sidebars and navigation sections.

In the spot where you've extracted the common HTML that you want Apache to insert, you'll need to add your include directive:

What this tells Apache is, look in the 'includes' directory for a file called 'header.html' and insert the HTML fragment found in that file into this .html file at this location.

The 'virtual' keyword allows you to specify a relative directory anywhere below the document root. It can also refer to a CGI program that will be executed and have the output insert into the HTML (note, for this functionality, you will need to use Includes instead of IncludesNoExec in the Apache configuration). The 'file' keyword is also supported, but it is slightly limited in that cannot refer to include files above the current file in the directory hierarchy. For this reason, 'virtual' is generally preferred.

Load Your Webpage

Time to fire up your web browser. Most Linux installs come with Firefox. Since we used localhost in our Apache configuration for the Virtual Host Server Alias, you can view your site at http://localhost/.

Enable Port Forwarding to VirtualBox

Up until now, we've been doing all of our work on our Linux install. If this install is a virtual machine, you may want to view your web pages from your Host OS. This is especially true if you're running Windows and you want to see if IE is behaving itself. To do this, you'll need to do some extra work with VirtualBox so that requests from the Host OS get routed to the Guest Linux install where Apache is running.

VirtualBox doesn't surface the port forwarding functionality through the UI (as of version 3.2.6). Instead you'll need to use the VBoxManage command-line utility to enable this on your host OS. My host OS is Windows, so the following assumes you are port forwarding from a Windows host to an Ubuntu (or Xubuntu or some derivative) guest OS.

To do this, you'll need the name you gave your guest OS when you set it up in VirtualBox, the port on the guest and the corresponding port on the host and the protocol that you're using. Here, those are Ubuntu, 80, 9999, and TCP. You also need to use a specific user defined key to refer to these settings, here we use the string 'apache' to identify the configuration in question. Shutdown your virtual machine, open a DOS command line prompt, navigate to where you have VirtualBox installed on your Windows machine and do the following:
VBoxManage setextradata Ubuntu "VBoxInternal/Devices/pcnet/0/LUN#0/Config/apache/HostPort" 9999 VBoxManage setextradata Ubuntu "VBoxInternal/Devices/pcnet/0/LUN#0/Config/apache/GuestPort" 80 VBoxManage setextradata Ubuntu "VBoxInternal/Devices/pcnet/0/LUN#0/Config/apache/Protocol" TCP

Now, it's possible that your virtual machine will throw an error. Double check that you typed everything correctly. If you did, then perhaps the 'pcnet' device is wrong and you need to use the alternate 'e1000'. I know this can happen because this is exactly what happened the first time I tried to do this. You can clear the previous settings and create the new settings like so.
VBoxManage setextradata Ubuntu "VBoxInternal/Devices/pcnet/0/LUN#0/Config/apache/HostPort" VBoxManage setextradata Ubuntu "VBoxInternal/Devices/pcnet/0/LUN#0/Config/apache/GuestPort" VBoxManage setextradata Ubuntu "VBoxInternal/Devices/pcnet/0/LUN#0/Config/apache/Protocol"

VBoxManage setextradata Ubuntu "VBoxInternal/Devices/e1000/0/LUN#0/Config/apache/HostPort" 9999 VBoxManage setextradata Ubuntu "VBoxInternal/Devices/e1000/0/LUN#0/Config/apache/GuestPort" 80 VBoxManage setextradata Ubuntu "VBoxInternal/Devices/e1000/0/LUN#0/Config/apache/Protocol" TCP
Sound like some obscure and cryptic set of commands? You bet, but no one said it would be easy. Peruse the VirtualBox documentation and you'll see this is only the tip of the esoteric iceberg.

Now, if everything worked correctly, you should be able to open a web browser in your Host windows OS and load the page by including the port number - http://localhost:9999/

We're Done

Congratulations, you've set up an Apache Web Server with Server-Side Includes on your local machine (and perhaps did some port forwarding to your virtual machine along the way). Now you can test out your website locally without uploading to your ISP to see how things look in all their hypertext glory. Speaking of, you'll still need to turn on Includes at your hosting provider, but they likely have a different way of doing that (that should be available in their help documentation).

Ruthless pragmatism and technical craftsmanship for the open web, the open mind and the open future.