Using Server-side-include on Apache

Posted by paul on 2013.11.07

Introduction

This tutorial will show you how to enable Server-side-include on CentOS Apache (httpd-2.2.15-29.el6.centos.x86_64). It is a great time saver. There are already other tutorials but I think another one won't hurt.

One thing that troubled me when I considered abandoning WordPress (and then Pelican later) as blogging platform was how to update navigation HTML in multiple html pages. I did not want to have to update dozens of HTML files every time navigation HTML needed to be updated. My 2 potential solutions were minimal navigation bar and Sublime's text replacement feature of multiple files. With the 2 partial 'solutions' in place, I started coding paulcodr.co with minimal html for navigation menu. It was simply an ordered list with 4 items. Formatting was done with external CSS. I used Sublime to update navigation bar a few times using the search/replace/in-multiple-files feature which is a really great tool. But it got tedious.

In practice the 2 'solutions' didn't really work out. The navigation menu is too minimal. Replacing text in multiple files with Sublime works ok, but gets tedious. And then I stumbled on Server Side Includes (aka SSI). I had not heard of SSI when I was going through book/tutorials on HTML, well because it's not exactly a component of HTML. But I think any guide on HTML should mention SSI. SSI is such a great time saver that any coder working with HTML should use it.

In this tutorial, I will show you how to use SSI. Note using SSI requires that you use .shtml, NOT .html. for HTML files. Some say it is ok to use .html but Apache documentation clearly states that you should use .shtml. For this reason, I will also show you how to format your website so that end users don't have to see .../index.shtml in the URL. Seeing http://yoursite.com/product/ is a better experience versus http://yoursite.com/product/index.shtml.

Requirements

  1. Apache web server that allows SSI
  2. Website with Document root at: /data/www/test/
  3. Website, http://yoursite.com/, running off of /data/www/test/
  4. Ability to upload files onto a website hosted on the Apache web server
  5. My tutorial is based on CentOS 6.x server
  6. Able to use vi or other CLI based text editor (find, edit, save)

If your website is already in operation and you would like to use SSI for maximum effect, you should first consider the possibility of having each webpage be in its own folder. It could be quite a bit of work but reason/benefit is obvious as explained later on this tutorial. Think about it. If you just want to learn about using SSI, nothing to worry about.

Edit httpd.conf

Open /etc/httpd/conf/httpd.conf to edit

Insert a line in httpd.conf

  1. httpd.conf has hundreds of lines of text. In it, find this section
  2. <Directory />
        Options FollowSymLinks
        AllowOverride None
    </Directory>
  3. Insert following line: Options +Includes
  4. You should end up with this.
  5. <Directory />
    Options FollowSymLinks
    Options +Includes
    AllowOverride None
    </Directory>
  6. Save /etc/httpd/conf/httpd.conf. However not done editing /etc/httpd/conf/httpd.conf yet.

Check 2 lines in httpd.conf are uncommented

  1. Still in /etc/httpd/conf/httpd.conf
  2. Ensure following lines are UNcommented. In my case, the lines were already uncommented.
  3. AddType text/html .shtml
    AddOutputFilter INCLUDES .shtml

Restart Apache service

In shell of CentOS, run following line to restart httpd service.

service httpd restart

Test if SSI file works

Create test.shtml

On your test website, create following test.shtml. In this example the file would be at /data/www/test/test.shtml

<HTML>
<TITLE>Test File</TITLE>

<!--#config timefmt="%A" --> <!--#echo var="DATE_LOCAL" -->

</HTML>

Grant permission for test.shtml

In shell run following commands

  1. chown apache:apache /data/www/test/test.shtml
  2. chmod 750 /data/www/test/test.shtml

View test.shtml with web browser

  1. Browse to http://yoursite.com/test.shtml and you should see day of the week (ex.: Thursday) in the webpage.
  2. Now your Apache server properly supports Server-Side-Includes.

Use SSI for navigation bar

  1. Next, simple tutorial on how to include Navigation bar in multiple HTML files using SSI. This is the real reason you would use SSI.
  2. Create index.shtml with following text.
  3. <!DOCTYPE html>
    <html>
    <head>
        <title>Test Nav</title>
    </head>
    <body>
    <p>Content here.</p>
    </body>
    </html>
  4. Create file (nav.html) with html snippet for navigation bar.
  5. <div id='navigation'>
        <ul>
            <li class='active'><a href='/'><span>Home</span></a></li>
            <li class='last'><a href='/about'><span>About</span></a></li>
        </ul>
    </div> <!-- end of navigation-->
  6. To have index.shtml be aware of nav.html, include following line
  7. <!--#include virtual="/nav.html" -->
  8. Now index.shtml will look like this:
  9. <!DOCTYPE html>
    <html>
    <head>
        <title>Test Nav</title>
    </head>
    <body>
        <!--#include virtual="/nav.html" -->
    <p>Content here.</p>
    </body>
    </html>
  10. Browse http://yoursite.com/index.shtml and you should see that the navigation section is included.

Using .shtml for all html pages

  1. Going forward, when you want to create a webpage with the navigation bar, you will just create .shtml with the following 1 line:
  2. <!--#include virtual="/nav.html" -->
  3. Later when you want to change the navigation bar website wide, you just need to update 1 file, nav.html. You do not need to go to EACH html page to update.

Each to his own (aka: each html file in own folder)

  1. For aesthetic and ease of maintenance, I recommend having each webpage be in its own folder. Doing this has some benefits.
  2. In a website already in operation, making the switch to using .shtml introduces another challenge, which is updating all html links on your website. Links that point to http://yoursite.com/about.html now need to be updated to http://yoursite.com/about.shtml. With a few dozens html files and a few links in each file, that can be hundreds of little changes. You could automate the change with script or text editors like Sublime. But it is a hassle. The fix is to have a folder for each webpage.
  3. Bad: Having About page at http://yoursite.com/about.html and linking to it with About.
  4. Good: You would have folder http://yoursite.com/about/ and put index.html in it. So you have http://yoursite.com/about/index.html. However when you link to About page from other webpages (or websites because your website is so popular), you use would use this link: About or About. Because Apache knows to return default file (usually index.html but to be changed to index.shtml later in this tutorial) when a link points to a folder, the user will still get the correct webpage. Also the URL in the browser will be http://yoursite.com/about/, NOT http://yoursite.com/about/index.html. Easier to read and remember.
  5. If a user directly typed in http://yoursite.com/about/index.shtml in URL bar, it will still work.
  6. Apache however normally is normally configured to look for and serve index.html, NOT index.shtml. Following section explains how to change that.
  7. Instead of switching to using index.shtml, I recommend you take this time to switch to linking to folder, not individual html file, on your website.

Change index page from index.html --> index.shtml

  1. To change index page from index.html --> index.shtml.
  2. Open /etc/httpd/conf/httpd.conf to edit.
  3. Find following line
  4. DirectoryIndex index.html index.html.var
  5. Insert index.shtml before index.html so it looks like this
  6. DirectoryIndex index.shtml index.html index.html.var
  7. Save httpd.conf
  8. Restart httpd service.
  9. service httpd restart
  10. That's it.