2. Downloading and Installing BRL

Installing BRL on your own web server involves installing and configuring a Java Web Application or Servlet. Most users will be able to install BRL using only the first section of this chapter. The remaining sections are needed only when using the obsolete jserv.

2.1 Easy Installation via learnbrl.war

Configuration of servlet containers has gotten a lot easier since this chapter was first written. A standard has been established for web applications such that they can be packaged up in a .war file that includes all the necessary .jar files and configuration directives.

The learnbrl.war file is one such web application. See section 2.3 Downloading BRL, but note that you may have to scroll down past the brl and kawa-brl packages to the bottom of the download page to find learnbrl.

For best use of the learnbrl tutorial, you should create a `learnbrl' directory under your servlet container's `webapps' directory. There you can unpack learnbrl with the following command:

jar xvf learnbrl.war

If you use a shared hosting service, use the above command in the directory that contains a WEB-INF subdirectory. You will need to edit WEB-INF/web.xml to change the parameter cut-uri servlet parameter to false. Follow your service provider's instructions for restarting your servlet engine.

Most shared hosting services use Apache. A convenient way to get started is to configure Apache to run .brl files through BRL. In the long run, it's better not to name URLs by the technology behind them, which might change over time. As a learning convenience, put the following in a `.htaccess' file in the directory where you'll put BRL files:

Action brlsv /servlet/brlsv AddHandler brlsv brl

This will facilitate you modifying the example files that are part of the tutorial.

2.2 Prerequisites

If you're using a Java web application server like Paperclips, Jetty, or Tomcat (among others), then everything you need to know was in the previous section. If you're using the obsolete JServ, this section and the ones that follow will be useful.

Before you can run BRL, you need the following:

1. A servlet engine that supports the Servlet API 2.1 or later.

2. Release 1.7 of Kawa, available from the BRL project page and elsewhere. See section 2.3 Downloading BRL. BRL will likely also work with future Kawa releases as they come out, but it may be necessary to recompile.

Your servlet engine should come with `SnoopServlet.class' or some other little test servlet. Do not try to install BRL until you've successfully tested such a servlet.

If you need further help, consult one of the following Usenet groups according to what OS your web server runs on:

• `comp.infosystems.www.servers.unix'
• `comp.infosystems.www.servers.mac'
• `comp.infosystems.www.servers.ms-windows'
• `comp.infosystems.www.servers.misc'

The rest of these instructions assume you already have servlets working. Consult your servlet engine's documentation for details. With JServ on Debian Gnu/Linux (potato release), I had to add the following lines to httpd.conf to get things working.

<IfModule mod_jserv.c> ApJServLogFile /var/log/jserv.log Include /etc/jserv/jserv.conf </IfModule>

2.3 Downloading BRL

You can get a compiled jar file or tar-gzipped sources from BRL's SourceForge Project Page, or via anonymous FTP.

2.4 Precompiled JAR Installation

1. Put the compiled jar files, `brl-2.2.jar' and `kawa-1.7.jar' into the CLASSPATH of your servlet engine. For example, if you are using JServ, add lines like the following to `jserv.properties':

   wrapper.classpath=/usr/local/share/java/brl-2.2.jar wrapper.classpath=/usr/local/share/java/kawa-1.7.jar

2. Extract `brl-global.scm' and `sitedefs.scm' from the BRL jar file and put them in a directory accessible to your servlet engine, but preferably not accessible to outsiders, as you might later put database passwords in `sitedefs.scm'.

   jar xvf brl-2.2.jar gnu/brl/brl-global.scm gnu/brl/sitedefs.scm

3. If your servlet engine allows it, configure the servlet gnu.brl.brlsv to be run for pages ending in `.brl'. For example, if you are using JServ, add the following directive to `jserv.conf':

   ApJServAction .brl /servlets/gnu.brl.brlsv

   Otherwise extract brlsv.class from the jar file and copy it to your servlets directory.

4. Set the servlet initialization parameter scmdir to the directory you put the `.scm' files in. For example, if you are using Jserv, add the following directive to `root.properties':

   servlet.gnu.brl.brlsv.initArgs=scmdir=/usr/local/com/brl

   If you would rather specify a location relative to the web root, you can set the servlet initialization parameter scmuri to such a path, e.g. /WEB-INF. Note: It has been reported that WEB-INF will not work with the Tomcat servlet engine, since the BRL servlet cannot access this directory after it has initialized. It needs to check if `sitedefs.scm' has been modified and reload it when necessary.

   By default the BRL servlet expects .brl files to be under your web server's document root. Some sites may prefer to put them in a different directory. Such sites should set the servlet initialization parameter brldir to the full path of that directory.

2.5 Building from Source

You need a Java compiler and a Unix-like make utility such as gmake. Issue the following shell command from the directory that contains a file called configure:

./configure

Then choose one of the following two commands for install:

If you want a jar file to put in your class path:

make all brl.jar

Note that the resultant `.jar' file has a name that includes the current version number, e.g. `brl-2.2.jar'. Follow the "Precompiled JAR Installation" instructions above.

If you want to install individual class files in `/usr/local/share/java':

make install

This method will also keep you from having to set the scmdir servlet parameter.

2.6 Testing Your Installation

Let's say your HTTP server is called example.com. If you have configured your servlet engine to run gnu.brl.brlsv for pages ending in `.brl', go to this URL:

http://example.com/noexist.brl

Otherwise go to this URL:

http://example.com/servlet/gnu.brl.brlsv/noexist.brl

If you get the usual "404 Not Found" error, then you have not successfully configured your servlet engine to run BRL. Go back to the documentation for your servlet engine. If you have correctly installed and configured BRL, then you should see a message with "Error" and "Debugging Info" sections, and "brl servlet" with a release number at the bottom.

The error message should say, "File not found". You should be able to tell from this error message exactly where the BRL servlet is trying to find files. Now you are ready to begin using BRL.

If a different error occurs, then something unusual about your servlet engine is causing problems. See section 1.2.1 Further Help.