changeset 23:7abc1ac0aece vendor

First import of documentation module
author robcast
date Thu, 17 Jan 2002 15:31:01 +0100
parents a6ddb285964d
children c4a571313422
files docu/installation.html
diffstat 1 files changed, 336 insertions(+), 0 deletions(-) [+]
line wrap: on
line diff
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docu/installation.html	Thu Jan 17 15:31:01 2002 +0100
@@ -0,0 +1,336 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
+<html>
+<head>
+<title>Installation of digilib</title>
+</head>
+
+<body>
+<h1>What you need to install digilib</h1>
+
+<ul>
+  <li>Java JDK &gt;1.2 (preferred 1.3)</li>
+  <li><a href="http://jakarta.apache.org/tomcat/index.html" >Jakarta
+  tomcat</a> version 4.0.1 from
+  http://jakarta.apache.org</li>
+  <li>The digilib distribution packages (from
+  http://penelope.unibe.ch/docuserver/digitallibrary/dist/)
+  <ul>
+    <li>digilib scripts and servlets package
+    <a href="http://penelope.unibe.ch/docuserver/digitallibrary/dist/digilib-core.zip"><code>digilib-core.zip</code></a></li>
+    <li>digilib configuration files for tomcat 4 package
+    <a href="http://penelope.unibe.ch/docuserver/digitallibrary/dist/digilib-tomconf.zip"><code>digilib-tomconf.zip</code></a></li>
+    <li>digilib external libraries package <a href="http://penelope.unibe.ch/docuserver/digitallibrary/dist/digilib-ext.zip"><code>digilib-ext.zip</code></a>
+    (Not essential. Contains documentation to JAI 1.1.1 and Xerces
+    1.4.3)</li>
+  </ul>
+  </li>
+</ul>
+
+<h1>Installation</h1>
+
+<h2>On Linux</h2>
+
+<ol>
+  <li>Make shure Java JDK is installed</li>
+  <li>Create a base directory for docuserver (the default used here is
+  <code>/docuserver</code>) and for the web interface
+  (<code>/docuserver/www</code>).</li>
+  <li>Unpack the <code>digilib-core</code> package in the web
+  interface directory (<code>/docuserver/www</code>). This will create
+  the digilib directory <code>digitallibrary</code>.</li>
+  <li>(optional) Unpack the <code>digilib-ext</code> package in the
+  docuserver directory.</li>
+  <li>Unpack Jakarta tomcat 4.0.1 in <code>/opt</code> This should
+  produce a directory <code>/opt/jakarta-tomcat-4.0.1</code>. Create a
+  link <code>/opt/tomcat</code> to the new directory.</li>
+  <li>Unpack the configuration files package
+  <code>digilib-tomconf</code> in the tomcat directory.</li>
+  <li>Adjust hostname and HTML-base directory in the file
+  <code>server.xml</code> (in the directory
+  <code>/opt/tomcat/conf</code>, see below for details))</li>
+  <li>Adjust the path to the JDK and its options in
+  <code>catalina.sh</code> (in the directory
+  <code>/opt/tomcat/bin</code>, see below for details)</li>
+  <li>(optional) For SuSE Linux you can use the startup skript
+  <code>tomcat/bin/rctomcat</code>
+  to start and stop the tomcat server. Copy the script into
+  <code>/etc/init.d</code> as <code>tomcat</code> and set runlevel
+  links accordingly.</li>
+  <li>(optional) Set the tomcat directory and all files to be owned by
+  the user
+  <code>wwwrun</code> (or whatever your webserver runs) and use this
+  account to start the tomcat server.</li>
+</ol>
+
+
+<!--
+<h2>Apache connector module</h2>
+
+<p>digilib currently needs to be accessed through the Apache
+webserver. There are two possible connectors for Apache and Tomcat4:
+<code>mod_webapp</code> and <code>mod_jk</code>. Only
+<code>mod_webapp</code> has been tested so far.</p>
+
+<ol>
+  <li>Get the sources for <code>mod_webapp</code></li>
+</ol>
+-->
+
+<h1>Configuration</h1>
+
+<h2>Tomcat</h2>
+
+<h3>catalina.sh</h3>
+
+<p>The file <code>catalina.sh</code> (in <code>/opt/tomcat/bin</code>
+has been modified to provide the path to the JDK and runtime options
+for the Java VM. Somewhere at the beginning of the file are two lines
+like this:</p>
+
+<pre>
+export JAVA_HOME=/usr/local/lib/IBMJava2-13
+export CATALINA_OPTS="-mx512m"
+</pre>
+
+<p>Adjust the <code>JAVA_HOME</code> path to point to your Java JDK
+installation directory. You can adjust the memory used by the Java VM
+with the <code>-mx512m</code> option.</p>
+
+<p>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 for linux mentioned
+above.</p>
+
+
+<h3>server.xml</h3>
+
+<p>The environment of the tomcat server is configured in the file
+<code>server.xml</code> in <code>/opt/tomcat/conf</code>. Extensive <a
+href="http://jakarta.apache.org/tomcat/tomcat-4.0-doc/index.html">documentation
+about all options</a> can by found on the webpages of the tomcat
+project.</p>
+
+<p>A minimal configuration file for running digilib is provided in the
+<code>digilib-tomconf</code> package. For standard operation only a
+few adjustments have to be made. The configuration file should look
+like this:</p>
+
+<pre>
+&lt;!-- Digilib Server Configuration File --&gt;
+
+&lt;Server port="8005" shutdown="SHUTDOWN" debug="0"&gt;
+
+  &lt;!-- Define an Apache-Connector Service --&gt;
+  &lt;Service name="Tomcat-Docuserver"&gt;
+
+    &lt;!-- Define a non-SSL HTTP/1.1 Connector on port 8080 --&gt;
+    &lt;Connector className="org.apache.catalina.connector.http.HttpConnector"
+               port=<b>"8080"</b> minProcessors="5" maxProcessors="75"
+               acceptCount="10" debug="0" connectionTimeout="60000"/&gt;
+
+    &lt;!-- Replace "localhost" with what your Apache "ServerName" is set to --&gt;
+    &lt;Engine className="org.apache.catalina.connector.warp.WarpEngine"
+     name="Apache" debug="1" appBase="webapps" defaultHost=<b>"hera.unibe.ch"</b>&gt;
+
+      &lt;!-- Global logger unless overridden at lower levels --&gt;
+      &lt;Logger className="org.apache.catalina.logger.FileLogger"
+              prefix="apache_log." suffix=".txt"
+              timestamp="true"/&gt;
+
+      &lt;!-- Define the default virtual host. Hostname must match the engine's. --&gt;
+      &lt;Host name=<b>"hera.unibe.ch"</b> debug="0" appBase=<b>"/docuserver/www"</b>&gt;
+
+        &lt;Context path="/docuserver/digitallibrary" docBase=<b>"/docuserver/www/digitallibrary"</b> debug="0" reloadable="false"&gt;
+	&lt;/Context&gt;
+
+      &lt;/Host&gt;
+
+      &lt;!-- Because this Realm is here, an instance will be shared globally --&gt;
+      &lt;Realm className="org.apache.catalina.realm.MemoryRealm" /&gt;
+
+    &lt;/Engine&gt;
+
+  &lt;/Service&gt;
+
+&lt;/Server&gt;
+</pre>
+
+<p>You can change the portnumber of your server to be something other
+than <b>8080</b> in the <code>port</code> property. If you want to use the
+default webserver port 80 you have to run tomcat as the root user (it
+is less secure to do this!).</p>
+
+<p>You have to change the occurences of <b>hera.unibe.ch</b> (in
+the <code>defaultHost</code> and <code>name</code> properties) to your
+hostname.</p>
+
+<p>Then you can adjust the <b>/docuserver/www</b> path to the
+directory where you installed the <code>digilib-core</code>
+package. You should not change the <code>path</code> property but only
+the <code>appBase</code> and <code>docBase</code> properties!</p>
+
+
+<h3>tomcat-users.xml</h3>
+
+<p>All passwords and usernames have to be set up in the file
+<code>tomcat-users.xml</code> in <code>/opt/tomcat/conf</code> if you
+want to use authentication in digilib. The file looks like this:</p>
+
+<pre>
+&lt;tomcat-users&gt;
+  &lt;user name="tomcat" password="tomcat" roles="tomcat" /&gt;
+  &lt;user name="role1"  password="tomcat" roles="role1"  /&gt;
+  &lt;user name="both"   password="tomcat" roles="tomcat,role1" /&gt;
+&lt;/tomcat-users&gt;
+</pre>
+
+<p>A user is identified by a <code>name</code> and
+<code>password</code>. 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
+<code>roles</code>. These roles will be used by digilib to decide if
+an authenticated user is allowed to access a document (see
+<code>digilib-auth.xml</code> below).</p>
+
+<p>tomcat has to be restarted before changes to
+<code>tomcat-users.xml</code> have effect!</p>
+
+<h2>Digilib</h2>
+
+<h3>web.xml</h3>
+
+<p>The deployment of the digilib servlets and JSPs is defined in the
+file <code>web.xml</code> in the <code>WEB-INF</code> subdirectory of
+the digilib directory
+(<code>/docuserver/www/digitallibrary/WEB-INF</code>).</p>
+
+<p>The only parameter you might have to adjust is the position of the
+digilib configuration file. The parameter occurs twice in the file and
+looks like this:</p>
+
+<pre>
+&lt;!-- parameters to the servlet --&gt;
+&lt;init-param&gt;
+  &lt;param-name&gt;config-file&lt;/param-name&gt;
+  &lt;param-value&gt;
+    <b>/docuserver/www/digitallibrary/WEB-INF/digilib-config.xml</b>
+  &lt;/param-value&gt;
+&lt;/init-param&gt;
+</pre>
+
+<p>Change the path to where you installed the configuration files.</p>
+
+<p>Make shure to change the parameter in both places! It is needed
+both for the servlet and the JSP pages!</p>
+
+<h3>digilib-config.xml</h3>
+
+<p>The main configuration for digilib is
+<code>digilib-config.xml</code>. It's position is defined by the
+<code>config-file</code> init-parameter to the servlets (see
+above).</p>
+
+<p>In the configuration file you can set several paths and
+options. The file looks like this:</p>
+
+<pre>
+&lt;!-- Digilib servlet config file --&gt;
+
+&lt;digilib-config&gt;
+  &lt;parameter name="debug-level" value="0" /&gt;
+
+  &lt;!--  Image to be sent to indicate general failure. --&gt;
+  &lt;parameter name="error-image" value=<b>"/docuserver/images/icons/broken.gif"</b> /&gt;
+
+  &lt;!--  Image to be sent to indicate authorization failure. --&gt;
+  &lt;parameter name="denied-image" value=<b>"/docuserver/images/icons/alert.red.gif"</b> /&gt;
+
+  &lt;!-- List of directories where images are searched.
+       Directories with low-resolution images are first in list. --&gt;
+  &lt;parameter name="basedir-list" value=<b>"/docuserver/scaled/small:/docuserver/images:/docuserver/scans/quellen"</b> /&gt;
+
+  &lt;!-- 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). --&gt;
+  &lt;parameter name="use-authorization" value="true" /&gt;
+
+  &lt;!-- 	  URL location of XML file with authorization requirements. --&gt;
+  &lt;parameter name="auth-file" value=<b>"/docuserver/www/digitallibrary/WEB-INF/digilib-auth.xml"</b> /&gt;
+
+  &lt;!-- Part of URL to indicate authenticated access to Tomcat. --&gt;
+  &lt;parameter name="auth-url-path" value="authenticated/" /&gt;
+&lt;/digilib-config&gt;
+</pre>
+
+<p>You have to adjust the <code>basedir-list</code> 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.</p>
+
+<p>You can supply your own images for the &quot;error&quot; and
+&quot;access denied&quot; messages by the servlet. Standard images
+will be used if these parameters are undefined.</p>
+
+<p>The <code>auth-file</code> parameter has to point to the
+authorization configuration file (see below).</p>
+
+
+<h3>digilib-auth.xml</h3>
+
+<p>The digilib access authorization is defined in the file defined by
+the <code>auth-file</code> parameter (usually
+<code>digilib-auth.xml</code> in <code>WEB-INF</code>). </p>
+
+<p>The file has two parts <code>diglib-paths</code> and
+<code>diglib-addresses</code>. It looks like this:</p>
+
+<pre>
+&lt;auth-config&gt;
+
+  &lt;digilib-paths&gt;
+    &lt;!-- 
+      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).  
+    --&gt;
+    &lt;path name="histast/eastwood-collection" role="eastwood-coll" /&gt;
+    &lt;path name="ptolemaios_geo" role="ptolemaios-geo" /&gt;
+  &lt;/digilib-paths&gt;
+
+  &lt;digilib-addresses&gt;
+    &lt;!-- 
+      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). 
+    --&gt;
+    &lt;address ip="127" role="local" /&gt;
+    &lt;address ip="130.92.68" role="eastwood-coll,ptolemaios-geo" /&gt;
+    &lt;address ip="130.92.151" role="ALL" /&gt;
+  &lt;/digilib-addresses&gt;
+
+&lt;/auth-config&gt;
+</pre>
+
+<p><code>diglib-paths</code> defines restricted directories and
+the roles needed for access. The roles are defined with the users in
+<code>tomcat-users.xml</code> (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.</p>
+
+<p><code>diglib-addresses</code> defines hosts or networks of
+computers that are automatically authenticated without username and
+password. Hosts can be assigned roles. The special keyword <code>ALL</code>
+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.</p>
+
+
+
+<hr>
+<address>robert.casties@philo.unibe.ch</address>
+<!-- hhmts start --> Last modified: Wed Jan 16 18:20:57 CET 2002 <!-- hhmts end -->
+</body> </html>