Barrel Installation and Configuration

This document describes the licensing terms for the Barrel software, how to install it, and how to configure and tune it to your needs once it is installed.


This is the "free" version of Barrel. It is copyright (c) 2003 Frank Carver, and licensed under the GNU Public License (GPL) version 2. If you wish to use the Barrel software, in whole or in part, in an application or situation incompatible with the GPL, we are willing to consider other, less-restrictive, licensing terms. Note, however, that there may be a charge for this option. Please contact us at to discuss your needs.


Have you got the latest version?

The latest version of Barrel is available from the Barrel Project at If you got this software or this document from another source, please check that you have the latest version.

Quick Installation

If you are in a hurry, Barrel can be installed as quickly as you can copy a file!.

You will need a working Servlet Container or Application Server which implements at least version 2.3 of the Java Servlet API. Barrel has been tested on Resin 2, and Tomcat 4, and sticks to the specification, so it should work on all other compliant servers. Please let us know if you find a server it won't work on..

All you need to do is drop the file "barrel.war" into the "webapps" directory of your servlet container. Most smart containers should recognize the new application automatically, but you may need to restart the container if yours gets confused. Once the container has recognized, deployed and initialized the web application (which may take a few minutes), check that it works by viewing the "web control panel". To view the control panel, append barrel to the URL of your server. For example, if I have a server at, I can access Barrel at, or if you have a server at http://localhost:8080/, you can access Barrel at http://localhost:8080/barrel. Now you can use the control panel to create, edit, preview and publish pages to your heart's content. See The Barrel User Guide for more details.

That was straightforward, wasn't it!

Warning! There is one thing to beware of if you run Barrel this way. Any changes you make or new pages you create will be stored in the "temporary directory" provided by the servlet container as part of the servlet specification. It's the only way to make an application work "out-of-the-box" like this, but it can be a little dangerous. The servlet API specification is vague about what should happen to the contents of this "temporary directory" if you reload or modify a web application. I can't control how your container behaves in this respect, and I'd hate to see a lot of hard work and information inadvertently lost if you upgrade or reinstall later. By all means run Barrel this way to check it out, and see how it works, but I strongly recommend that you configure your installed Barrel to use a different, more permanent, directory for your files before you use it "for real".

Configuration and Customization

Barrel is extremely configurable. In fact, almost anything may be configured or customised, often in more than one way. Barrel may be configured or customised by altering values, styles, templates, or code:

Values and styles are the simplest to change, in most cases just requiring that you edit existing files. The great majority of common customisations can be done just with values and styles. To change the templates, it is necessary to "expand" the delivered "war" file, and edit files within the web application folder. If you change any templates you may need to re-start the web container to make sure it notices the changes. Source code for both the Barrel application and the libraries it uses are also available for download, so if you wish, you can alter and rebuild enything in the system.

Simple Barrel value changes

  1. Locate the top-level tmp directory. On Unix/Linux/BSD/OSX systems look for /tmp it should already be present. On Windows systems, find or create a directory tmp at the "top" of the drive you run your your servlet container from.
  2. Create and edit a file barrel.prp in this tmp directory. This file is in "properties" format. Each line of the file is either a comment line (starting with '#'), a blank line, or has the form name=value.
  3. If the value you wish to change is already in this file, simply change the right-hand part (after the '=') to your new value. To create a new entry, simply add a new line with a new name on the left-hand side, and a new value on the right-hand side.

  4. When you have changed all the values you wish to change, re-start the servlet container to pick up the changes.

If you can't create or edit the file /tmp/barrel.prp, or you are working on a multi-user system and feel that /tmp is not a secure enough location for configuration files, you will need to "expand" the web application as decribed later, and change where Barrel looks for its application properties.

To change where page definitions are stored

One of the first "customizations" you should consider is where the page definitions are stored. Note that Barrel stores the definitions of the pages separately from the actual HTML pages served by the web server. This allows all the pages on a site to be automatically updated when you decide to change the style or layout of your pages. It is most important that you look after these page definitions and don't let them get accidentally deleted or overwritten and they represent the "content" of your web site.

Find or make a directory which is unlikely to be deleted or messed with by another user or another system process. Make sure that it is both readable and writable by the user your servlet container runs as, and that it is initially empty.

Add a line like the following to the barrel.prp file (substitute your chosen location):

following the instructions above.

After you re-start the servlet container, go to the control panel, then upload and publish some pages to make sure it works. Check that a file for each page has appeared in your chosen location. Note that page definition files typically have the extension ".tract".

To change where published "live" pages are placed

Because Barrel stores the definitions of the pages separately from the actual HTML pages used by the web server, you need to "publish" a site to be able to access it over the web. By default, Barrel publishes pages to the "temporary directory" supplied by the servlet container, and provides a special servlet to show the styled pages. If you want to serve styled pages using a regular web server such as Apache, you need to tell Barrel where to put the pages

Add a line like the following to the barrel.prp file (substitute your chosen location):

following the instructions above.

Please be very careful with this configuration. When you use Barrel to publish pages, it will overwrite any files with similar names in the chosen directory. This includes automatically generating common files such as "index.html". Make sure you take a copy of all files from your chosen directory before you run Barrel and publish pages. After you re-start the servlet container, go to the control panel, then create and publish some pages to make sure it works. Check that a file for each page has appeared in your chosen location.

To change basic page style and appearance

Barrel uses CSS for most styling of published pages. CSS is very powerful, and the basic HTML pages generated by Barrel are built with CSS in mind, so it is easy to completely change the look of a whole site by just changing a single file, without even re-publishing the pages.

The default CSS style definitions are contained in the file barrel_style.css, which is automatically placed with the published pages if not already present. Once the default styles have been published you are free to modify the file to alter the style of your pages. Bear in mind that if you do this, and you wish to make use of the "preview" facility, you will need to make sure your changed style definitions are also copied to the "preview" directory.

More Complex Changes

The following configuration and customization instructions assume you have an "expanded" installation of the Barrel web application "war" file. All files mentioned are relative to this expanded directory.

Almost all servlet containers expand each web application into its own directory when it is deployed. If your server doesn't automatically expand the deployed web application you will need to expand it yourself using something like "WinZip" or "jar". You should make sure that you expand the "war" to a subdirectory of a directory monitored by the server. Typically this will be the same "webapps" directory in which you placed the "war" file, so you could for example use jar xf Barrel.war Barrel.

Before you start modifying the expanded web application, you should remove the original "war" file from the webapps directory, to ensure you don't get any conflicts. This may require stopping the server.

Some servlet containers will automatically detect a change to web.xml or other files and reload the web application after your changes. For others you will need to restart the server.

To change the name of the application

I find it hard to imagine, but you may not want to offer an application called "Barrel" on your web site. If this is the case, you can call the application anything you like (within the limits of acceptable URL directory names).

  1. Stop your servlet container. Although there may be servers which can take an application being renamed in their stride, most can't. So I recommend stopping the servlet container just to be sure. You may also find that your servlet container maintains file locks on some of the files in the application, and won't let you change it while the server is running.

  2. Rename the expanded application directory to your chosen name. If you are still using the default "container temporary directory" for page storage, you may also need to move your pages to whatever temporary directory the server chooses for the new application name.

  3. Restart your server. Access Barrel using your new application name.

To install more than one copy of Barrel on the same domain

If you wish to install more than one Barrel on your web site (for example, one for staff use, and one for customer use, or one for each of your product areas), you can't call both of them "Barrel". Follow the process described above in "to change the name of the application", but copy the directory rather than moving it. Remember to configure each Barrel instance to use a different directory for page storage, or things may get very confusing!

Using this technique will allow you to install as many Barrel's as you want.

To alter page generation templates

The default page style of Barrel is functional but bland. You can easily change most features of the page style with CSS (as described above), but some things are so fundamental that you need to actually change the underlying HTML.

  1. In the directory WEB-INF/classes you will some files with the filetype extension ".tract" or ".tpl". These are the page templates used whenever Barrel generates a web page. The difference between the two types is that ".tract" files have header lines containing comments, value settings, or a "prolog" to be run before using the template. ".tpl" files contain just the text of the template.

  2. Each template may be any valid HTML page, however you wish to generate it. If you look at the original templates you will see patterns like @CONTENT@. These show where values from the loaded page will be substituted. Note that for maximum felxibility I suggest that you follow the conventions of using XHTML and annotating all the significant sections with class and id attributes so they can easily be styled using CSS.

Version 1.0.110 Aug 2003 Frank Carver Logo