What you need to install digilib

Installation

On Linux/Unix

  1. Make shure the Java JDK is installed (a JRE won't do).
  2. Create a base directory for docuserver (the default used here is /docuserver) and for the web interface (/docuserver/www).
  3. Unpack the alcatraz-core package in the web interface directory (/docuserver/www). This will create the digilib directory digitallibrary.
  4. Unpack Jakarta Tomcat 4.1.24 in /docuserver This should produce a directory /docuserver/jakarta-tomcat-4.1.24. Create a link /docuserver/tomcat to the new directory.
  5. (optional) Unpack the configuration files package digilib-tomconf in the tomcat directory.
  6. Create a link from the digilib directory into the Tomcat webapps directory /docuserver/tomcat/webapps (type ln -s /docuserver/www/digitallibrary /docuserver/tomcat/webapps) This is the default installation running on port 8080 as http://myserver:8080/digitallibrary/.
  7. Adjust the path to the JDK and its options in catalina.sh (in the directory /docuserver/tomcat/bin, see below for details)
  8. (optional) For SuSE Linux you can use the startup skript tomcat/bin/rctomcat to start and stop the tomcat server. Copy the script into /etc/init.d as tomcat and set runlevel links accordingly.
  9. (optional) Set the tomcat directory and all files to be owned by the user wwwrun (or whatever your webserver runs) and use this account to start the tomcat server.
  10. (optional) To use Mozilla-XUL functionality Alcatraz users have to open the page http://myserver:8080/docuserver/digitallibrary/xul/install.html in a Mozilla compatible browser. There the users can find instructions to install XUL-Components into their browser.

On Windows (quick install)

Set the following Environment Variables:
CATALINA_HOME = C:\jakarta-tomcat-4.1.24 (or similar)
JAVA_HOME = C:\j2sdk (or similar)

Start Tomcat server: Open a console window (start cmd.exe).
Type: %CATALINA_HOME%\bin\startup

Try the following URL in your browser: http://localhost:8080 or http://127.0.0.1:8080

You should now be able to see the Tomcat opening screen: If you're seeing this page via a web browser, it means you've setup Tomcat successfully. Congratulations!

Shut it down again: In the console window type %CATALINA_HOME%\bin\shutdown.

Extract the "Alcatraz" distribution, possibly to C:\docuserver. Modify the following configuration files according to your paths (as in the "On Linux" section):

For tomcat

For digilib

In the alcatraz-win-conf.zip package you can find prepared configuration files with the following default values:

Now you can restart the Tomcat server: http://localhost:9090 or http://127.0.0.1:9090.

Watch the images: http://localhost:9090/docuserver/digitallibrary/digilib.jsp?&lv=2

Configuration

Tomcat

catalina.sh / catalina.bat

The file catalina.sh (in /docuserver/tomcat/bin can be modified to provide the path to the JDK and runtime options for the Java VM. Somewhere at the beginning of the file you can put two lines like this:

export JAVA_HOME=/usr/local/lib/IBMJava2-14
export CATALINA_OPTS="-mx512m"

or, on Windows

set CATALINA_HOME=C:\jakarta-tomcat-4.1.24
set JAVA_HOME=C:\j2sdk

Adjust the JAVA_HOME path to point to your Java JDK installation directory. You can adjust the memory used by the Java VM with the -mx option.

You can delete those two lines if you set these variables in your shell before starting tomcat in that same shell. These lines are needed if you want to use the startup script mentioned above under linux .

tomcat-users.xml

All passwords and usernames have to be set up in the file tomcat-users.xml in /docuserver/tomcat/conf if you want to use authentication in digilib. The file looks like this:

<tomcat-users>
  <user name="tomcat" password="tomcat" roles="tomcat" />
  <user name="role1"  password="tomcat" roles="role1"  />
  <user name="both"   password="tomcat" roles="tomcat,role1" />
</tomcat-users>

A user is identified by a name and password. These two elements have to be entered in a authentication form presented by the browser when accessing a restricted resource. A user can have one or more roles. These roles will be used by digilib to decide if an authenticated user is allowed to access a document (see digilib-auth.xml below).

If you want to use the webinterface to configure Tomcat, you have to add administrational account with the roles admin and manager.

tomcat has to be restarted before changes to tomcat-users.xml have effect!

Digilib

web.xml

The deployment of the digilib servlets and JSPs is defined in the file web.xml in the WEB-INF subdirectory of the digilib directory (/docuserver/www/digitallibrary/WEB-INF).

The only parameter you will have to adjust is the position of the digilib configuration file. The parameter occurs twice in the file and looks like this:

<!-- parameters to the servlet -->
<init-param>
  <param-name>config-file</param-name>
  <param-value>
    /docuserver/www/digitallibrary/WEB-INF/digilib-config.xml
  </param-value>
</init-param>

Change the path to point where you installed the configuration files.

Make shure to change the parameter in both places in the config file! It is needed both for the servlet and the JSP pages!

digilib-config.xml

The main configuration for digilib is digilib-config.xml. It's position is defined by the config-file init-parameter to the servlets (see above).

In the configuration file you can set several paths and options. The file looks like this:

<!-- Digilib servlet config file -->

<digilib-config>
  <parameter name="debug-level" value="0" />

  <!--  Image to be sent to indicate general failure. -->
  <parameter name="error-image" value="/docuserver/images/icons/broken.gif" />

  <!--  Image to be sent to indicate authorization failure. -->
  <parameter name="denied-image" value="/docuserver/images/icons/alert.red.gif" />

  <!-- List of directories where images are searched.
       The authoritative directory with the high-resolution images
       is first in list. -->
  <parameter name="basedir-list" value="/docuserver/images:/docuserver/scaled/small" />

  <!-- Java class to use for image operations -->
  <parameter name="docuimage-class" value="digilib.image.JAIDocuImage" />

  <!-- is sending whole image files with mo=file allowed? -->
  <parameter name="sendfile-allowed" value="true" />

  <!-- Restrict access to authorized users.
       User authentication and roles are provided by the servlet container 
       (see tomcat-users.xml).
       Authorization for resources (directories) is evaluated by the servlet 
       (see auth-file). -->
  <parameter name="use-authorization" value="true" />

  <!-- Location of XML file with authorization requirements. -->
  <parameter name="auth-file" value="/docuserver/www/digitallibrary/WEB-INF/digilib-auth.xml" />

  <!-- Part of URL to indicate authenticated access to Tomcat. -->
  <parameter name="auth-url-path" value="authenticated/" />
</digilib-config>

You have to adjust the basedir-list parameter to the directories where your images are installed. You need only one directory if you do not have prescaled low resolution versions of your images. The directory with the high-resolution versions must be the first entry in the list.

You can supply your own images for the "error" and "access denied" messages by the servlet. Standard images will be used if these parameters are undefined.

The auth-file parameter has to point to the authorization configuration file (see below).

You can specify the Java toolkit implementation with the docuimage-class parameter. The ImageLoaderDocuImage might give best performance but works only with JDK 1.4 and up. JAIDocuImage works with JDK 1.3 and up.

digilib-auth.xml

The digilib access authorization is defined in the file defined by the auth-file parameter (usually digilib-auth.xml in WEB-INF).

The file has two parts diglib-paths and diglib-addresses. It looks like this:

<auth-config>

  <digilib-paths>
    <!-- 
      A user must supply one of the roles under "role"
      to access the directory "name".
      Roles under "role" must be separated by comma only (no spaces).  
    -->
    <path name="histast/eastwood-collection" role="eastwood-coll" />
    <path name="ptolemaios_geo" role="ptolemaios-geo" />
  </digilib-paths>

  <digilib-addresses>
    <!-- 
      A computer with an ip address that matches "ip"
      is automatically granted all roles under "role".
      The ip address is matched from the left (in full quads).
      Roles under "role" must be separated by comma only (no spaces). 
    -->
    <address ip="127" role="local" />
    <address ip="130.92.68" role="eastwood-coll,ptolemaios-geo" />
    <address ip="130.92.151" role="ALL" />
  </digilib-addresses>

</auth-config>

diglib-paths defines restricted directories and the roles needed for access. The roles are defined with the users in tomcat-users.xml (see above). All subdirectories of the given directories have the same restrictions. All directories not listed here (and not subdirectories of listed directories) are freely accessible.

diglib-addresses defines hosts or networks of computers that are automatically authenticated without username and password. Hosts can be assigned roles. The special keyword ALL authorizes for everything. If the role assigned to the computer is not sufficient to access a resource the user will be asked for username and password.

robert.casties@philo.unibe.ch
Last modified: Tue Sep 16 20:37:12 CEST 2003