view docu/installation.html @ 112:28e449fa185c

small updates
author robcast
date Wed, 14 May 2003 12:49:41 +0200
parents ffc7d9138397
children 7a237ba63a3d
line wrap: on
line source

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<html>
<head>
<title>Installation of alcatraz/digilib</title>
</head>

<body>
<h1>What you need to install digilib</h1>

<ul>
  <li>Java JDK &gt;1.2 (preferred 1.4 and up)</li>
  
  <li><a href="http://jakarta.apache.org/tomcat/index.html" >Jakarta
  Tomcat</a> version 4 or later (preferred 4.1 and up) from
  <a href="http://jakarta.apache.org<" >http://jakarta.apache.org</a></li>
  
  <li>The digilib distribution packages (from
  <a href="http://developer.berlios.de" >http://developer.berlios.de</a>)
  <ul>
    <li>alcatraz/digilib scripts and servlets package
    <a href="http://download.berlios.de/digilib/alcatraz-core-0.3.zip"><code>alcatraz-core.zip</code></a></li>
    <li>digilib configuration files for tomcat 4 package
    <a href="http://download.berlios.de/digilib/alcatraz-tomconf-0.1.zip"><code>alcatraz-tomconf.zip</code></a> (Not essential)</li>
  </ul>
  </li>
</ul>

<h1>Installation</h1>

<h2>On Linux</h2>

<ol>
  <li>Make shure the Java JDK is installed (a JRE won't do).</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>alcatraz-core</code> package in the web
  interface directory (<code>/docuserver/www</code>). This will create
  the digilib directory <code>digitallibrary</code>.</li>

  <li>Unpack Jakarta Tomcat 4.1.24 in <code>/docuserver</code> This should
  produce a directory <code>/docuserver/jakarta-tomcat-4.1.24</code>. Create a
  link <code>/docuserver/tomcat</code> to the new directory.</li>

  <li>(optional) Unpack the configuration files package
  <code>digilib-tomconf</code> in the tomcat directory.</li>

  <li>Create a link from the digilib directory into the Tomcat webapps
  directory <code>/docuserver/tomcat/webapps</code> (type <code>ln -s
  /docuserver/www/digitallibrary /docuserver/tomcat/webapps</code>) This is
  the default installation running on port 8080 as
  <code>http://myserver:8080/digitallibrary/</code>.</li>

  <li>Adjust the path to the JDK and its options in
  <code>catalina.sh</code> (in the directory
  <code>/docuserver/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>

  <li>(optional) To use Mozilla-XUL functionality Alcatraz users have
  to open the page
  <code>http://myserver:8080/docuserver/digitallibrary/xul/install.html</code>
  in a Mozilla compatible browser. There the users can find
  instructions to install XUL-Components into their browser. </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>/docuserver/tomcat/bin</code>
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:</p>

<pre>
export JAVA_HOME=/usr/local/lib/IBMJava2-14
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>-mx</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 mentioned above under
linux .</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>/docuserver/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>If you want to use the webinterface to configure Tomcat, you have to
add administrational account with the roles <code>admin</code> and
<code>manager</code>.</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 will 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 point where you installed the configuration files.</p>

<p>Make shure to change the parameter in both places in the config
file! 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.
       The authoritative directory with the high-resolution images
       is first in list. --&gt;
  &lt;parameter name="basedir-list" value=<b>"/docuserver/images:/docuserver/scaled/small"</b> /&gt;

  &lt;!-- Java class to use for image operations --&gt;
  &lt;parameter name="docuimage-class" value="digilib.image.JAIDocuImage" /&gt;

  &lt;!-- is sending whole image files with mo=file allowed? --&gt;
  &lt;parameter name="sendfile-allowed" value="true" /&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;!-- 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. The directory with the high-resolution versions must be the
first entry in the list.</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>

<p>You can specify the Java toolkit implementation with the
<code>docuimage-class</code> parameter. The
<code>ImageLoaderDocuImage</code> might give best performance but
works only with JDK 1.4 and up. <code>JAIDocuImage</code> works with
JDK 1.3 and up.</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>casties@mpiwg-berlin.mpg.de</address>
<!-- hhmts start -->Last modified: Wed May 14 12:49:14 CEST 2003 <!-- hhmts end -->
</body> </html>