Mercurial > hg > digilib-old
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 >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> +<!-- Digilib Server Configuration File --> + +<Server port="8005" shutdown="SHUTDOWN" debug="0"> + + <!-- Define an Apache-Connector Service --> + <Service name="Tomcat-Docuserver"> + + <!-- Define a non-SSL HTTP/1.1 Connector on port 8080 --> + <Connector className="org.apache.catalina.connector.http.HttpConnector" + port=<b>"8080"</b> minProcessors="5" maxProcessors="75" + acceptCount="10" debug="0" connectionTimeout="60000"/> + + <!-- Replace "localhost" with what your Apache "ServerName" is set to --> + <Engine className="org.apache.catalina.connector.warp.WarpEngine" + name="Apache" debug="1" appBase="webapps" defaultHost=<b>"hera.unibe.ch"</b>> + + <!-- Global logger unless overridden at lower levels --> + <Logger className="org.apache.catalina.logger.FileLogger" + prefix="apache_log." suffix=".txt" + timestamp="true"/> + + <!-- Define the default virtual host. Hostname must match the engine's. --> + <Host name=<b>"hera.unibe.ch"</b> debug="0" appBase=<b>"/docuserver/www"</b>> + + <Context path="/docuserver/digitallibrary" docBase=<b>"/docuserver/www/digitallibrary"</b> debug="0" reloadable="false"> + </Context> + + </Host> + + <!-- Because this Realm is here, an instance will be shared globally --> + <Realm className="org.apache.catalina.realm.MemoryRealm" /> + + </Engine> + + </Service> + +</Server> +</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> +<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> +</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> +<!-- parameters to the servlet --> +<init-param> + <param-name>config-file</param-name> + <param-value> + <b>/docuserver/www/digitallibrary/WEB-INF/digilib-config.xml</b> + </param-value> +</init-param> +</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> +<!-- 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=<b>"/docuserver/images/icons/broken.gif"</b> /> + + <!-- Image to be sent to indicate authorization failure. --> + <parameter name="denied-image" value=<b>"/docuserver/images/icons/alert.red.gif"</b> /> + + <!-- List of directories where images are searched. + Directories with low-resolution images are first in list. --> + <parameter name="basedir-list" value=<b>"/docuserver/scaled/small:/docuserver/images:/docuserver/scans/quellen"</b> /> + + <!-- 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" /> + + <!-- URL location of XML file with authorization requirements. --> + <parameter name="auth-file" value=<b>"/docuserver/www/digitallibrary/WEB-INF/digilib-auth.xml"</b> /> + + <!-- Part of URL to indicate authenticated access to Tomcat. --> + <parameter name="auth-url-path" value="authenticated/" /> +</digilib-config> +</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 "error" and +"access denied" 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> +<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> +</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>