I’ve been visiting an awesome community space in Oakland called The Omni Commons. While here I’ve been participating in some of their meetings and working groups. The other day some changes were requested to be made to the main website, I wanted to help out and decided to jump in!
The website has a repository on github.com which I forked and cloned down to my machine. It appears to be a straight forward HTML5 site but when I opened it in my browser none of the css files were rendering. I looked to see if maybe there was an issue with relative links to the resources but found no missing resources. Upon looking at the head I found no trace of any links to other resources only this cryptic include:
<!--#include virtual="/includes/nav.html" -->
The README.md file didn’t help at all (it was pretty much blank) and after some head scratching and some searching around I found out what this little bit of code is, a…
Server Side Include (SSI)
It is (according to Wikipedia) a simple interpreted server-side scripting language used almost exclusively for the Web.
I’d never heard of it but it seemed very cool and it is a nice little trick for including blocks of HTML code without having to rely on a modern website template engine which often requires having Ruby or Node or some other code base running. No this is old school, run directly through the web server, such as Apache.
It turns out that for SSI to work it has to be run on a server which is configured to render such files. I set up my virtual host and fired up the website once more.
No dice, the pages still weren’t rendering. I then found this tutorial from linuxtopia.org which describes how to configure the localhost to render includes. I then took to writing up some documentation in the README file of the project so that the next person who wanted to set up a local instance of the site knew what was going on. I’ve reproduced some of those instructions below.
Setting up Server Side Includes on Localhost
The Omni Commons website uses Server Side Includes (SSI) to pull in head, nav, and footer html from the
/includes folder. So we need to set up your local environment to handle this. Much of the following information is taken from linuxtopia.org’s how to guide on apache ssi.
The SSI strings look like this:
<!--#include virtual="/includes/nav.html" -->
Once SSI is enabled this line will be replaced by the content of
/includes/nav.html. This allows us to edit the nav once and have those changes appear on all pages with the above snippet.
The first thing to do is ensure that your server has the mod_include module installed and enabled.
The following instructions were tested on an Mac OS X (10.9) machine but should work on any Linux machine as well.
First we will examine the Apache Config file
httpd.conf typically located at:
Make sure that the includes modual is present and active by searching for
mod_include within the
httpd.conf file, look for this line:
LoadModule include_module libexec/apache2/mod_include.so
Check that there isn’t a hash (#) in front of the above text (you’re text might differ slightly).
Turn on Includes
You’ll want to turn on the include option through your virtual host by adding:
Here’s Drew’s vhost as an example:
<Virtualhost *:80> VirtualDocumentRoot "/Users/drew/www/%-2/" ServerName vhosts.localhost ServerAlias *.localhost ErrorLog "/var/log/apache2/vhosts.localhost-error_log" <Directory "/Users/drew/www/*"> Options Indexes FollowSymLinks +Includes AllowOverride All Order allow,deny Allow from all </Directory> </Virtualhost>
Side Note: Drew is using a nifty trick to automagically add folders in
/Users/drew/www/ to their virtual host, you can read more about that on Glen Scott’s blog post Simple Development Hosts on Mac
Pay attention to the line where
+Includes has been added:
Options Indexes FollowSymLinks +Includes
Now we need to tell Apache to scan the proper files for includes. Typically, due to the extra server overhead, this is done only to files that are specified as having includes by using a special extension
.shtml to indicate to the system that they should be scanned.
The OmniCommons website uses
.html throughout, so we simply need to tell our local apache server to scan all
.html files for includes.
Go back to your
httpd.conf and find the line with
#AddOutputFilter INCLUDES .shtml now add under that line:
AddOutputFilter INCLUDES .html
The hash (#) indicates that a line is commented out, because we want the config file to read our command we omit that hash. So this command is adding an output filter (
AddOutputFilter) that applies Includes (
INCLUDES) to all html files (
You should now be able to visit your virtual host, in Drew’s case it is
Remember: The apache include will not run if you open the .html file directly in your browser, it must be served from the virtual host.