# HG changeset patch # User robcast # Date 1099398536 -3600 # Node ID c70a5016fdc5612c838edf52391f031b20c25952 # Parent ccddc9a5b63b4e64d2aeedf0022ee2dd6b100414 new doc diff -r ccddc9a5b63b -r c70a5016fdc5 client/doc/digilib_install.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/client/doc/digilib_install.html Tue Nov 02 13:28:56 2004 +0100 @@ -0,0 +1,365 @@ + + + +Installation of digilib + + + +

What you need to install digilib

+ +

+ Java JDK >1.2 (preferred 1.4 and up) +
+ Jakarta + Tomcat version 4 or later (preferred 4.1 and up) from + http://jakarta.apache.org +
The digilib distribution package digilib-core.zip (from + http://developer.berlios.de) + +
Some auxiliary Java libraries to be put in digitallibrary/WEB-INF/lib (can also be found in the digilib-ext.zip package) +
- + concurrent.jar from Doug Lea's util.concurrent library (see http://gee.cs.oswego.edu/dl/). +
- + log4j.jar from the Log4J library (see http://logging.apache.org) +
- + jai_imageio.jar (and its native libraries) with JDK >= 1.4, from the Java Advanced Imaging Image-IO Tools (see http://java.sun.com/products/java-media/jai/) +
- + jai_core.jar, jai_codec.jar if you want to use the JAIDocuImage implementation, from the Java Advanced Imaging API (see http://java.sun.com/products/java-media/jai/) +
- + batik-*.jar if you want to use the Raster servlet, from the Apache Batik library (see http://xml.apache.org/batik/) +
- + jena.jar from the JENA RDF library version 1.6.1 (see http://jena.sourceforge.net/) +
+

+ +

Installation

+ +

On Linux/Unix

+ +

Make shure the Java JDK is installed (a JRE won't do).
Create a base directory for digilib (the default used here is + /docuserver) and for the web interface + (/docuserver/www).
Unpack the digilib-core.zip package in the web + interface directory (/docuserver/www). This will create + the digilib directory digitallibrary.
Install the auxiliary Java libraries in + digitallibrary/WEB-INF/lib. (Or just unpack the + digilib-ext.zip package there.)
Unpack Jakarta Tomcat 5.0.29 in /docuserver This should + produce a directory /docuserver/jakarta-tomcat-5.0.29. Create a + link /docuserver/tomcat to the new directory.
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 installs + digilib in the default Tomcat instance running on port 8080 as + http://myserver:8080/digitallibrary/.
Adjust the path to the JDK and its options in + catalina.sh (in the directory + /docuserver/tomcat/bin, see below for details)

+ + +

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 diglib-core.zip package, possibly to C:\docuserver. +
+Install the auxiliary Java libraries in digitallibrary\WEB-INF\lib. +(Or just unpack the digilib-ext.zip package there.) +
+ Modify the following configuration files according to your paths (as in the "On Linux" section): +
+For tomcat +
- C:\jakarta-tomcat-4.1.24\conf\server.xml
- C:\jakarta-tomcat-4.1.24\conf\tomcat-users.xml
+For digilib +
- C:\docuserver\digitallibrary\WEB-INF\digilib-config.xml
- C:\docuserver\digitallibrary\WEB-INF\digilib-auth.xml
+In the alcatraz-win-conf.zip package you can find +prepared configuration files with the following default values: +
- The image file directory is C:\bilder.
- The username for viewing image files is digilib.
- The password for viewing image files is digilib.
- The digilib server runs on Port 9090.
+
+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 +

+ + +

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.

+ + +

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

+ +

digilib-config.xml

+ +

The main configuration for digilib is +digilib-config.xml. It's normally in the +WEB-INF directory in the webapp. (If you really need +another location you can define it in the config-file +init-parameter to the servlet)

+ +

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

+ +

+<!-- Digilib servlet config file -->
+
+<digilib-config>
+  <!--  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" />
+
+  <!-- mimimum amount of scaling done with antialiasing -->
+  <parameter name="subsample-minimum" value="2"/>
+  
+  <!-- default interpolation quality (0=worst) -->
+  <parameter name="default-quality" value="1"/>
+  
+  <!-- is sending whole image files with mo=file allowed? -->
+  <parameter name="sendfile-allowed" value="true" />
+
+  <!-- the a maximum size of any sent image. (0 means no limit) -->
+  <parameter name="max-image-size" value="0" />
+
+  <!-- use safe but slow directory indexing -->
+  <parameter name="safe-dir-index" value="false" />
+
+  <!-- number of working threads -->
+  <parameter name="worker-threads" value="2" />
+
+  <!-- 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="digilib-auth.xml"/>
+
+  <!-- Part of URL to indicate authenticated access to Tomcat. -->
+  <parameter name="auth-url-path" value="authenticated/"/>
+
+  <!-- use mapping of "virtual directories" to real directories on the server --
+>
+  <parameter name="use-mapping" value="false"/>
+  
+  <!-- location of XML mapping file -->
+  <parameter name="mapping-file" value="digilib-map.xml"/>
+  
+  <!-- location of logger config file -->
+  <parameter name="log-config-file" value="log4j-config.xml"/>
+</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 don't provide prescaled low resolution versions of your +images. The directory with the high-resolution images must be the +first entry in the list.

+ +

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

+ +

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.

+ + + +

robcast@mail.berlios.de

+Last modified: Tue Nov 2 13:14:57 CET 2004 +