Mercurial > hg > digilib-old
view docu/installation.html @ 22:37eae12d4148
Initial revision
| author | robcast |
|---|---|
| date | Thu, 17 Jan 2002 15:31:01 +0100 |
| parents | |
| children | dd49040ae5a5 |
line wrap: on
line source
<!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>