Mercurial > hg > digilib-doc
view digilib_install.html @ 0:7b20d15a57e9
refactored into maven modules per servlet type.
can build servlet-api 2.3 and 3.0 via profile now!
| author | robcast |
|---|---|
| date | Tue, 26 Apr 2011 20:24:31 +0200 |
| parents | |
| children | 5baf44fed7b0 |
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> <a href="http://java.sun.com/downloads/index.html" >Java JDK</a> >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 package <a href="http://download.berlios.de/digilib/digilib-core.zip"><b>digilib-core.zip</b></a> (from <a href="http://developer.berlios.de">http://developer.berlios.de</a>) </li> <li>Some auxiliary Java libraries to be put in <code>digitallibrary/WEB-INF/lib</code> (can also be found in the <a href="http://download.berlios.de/digilib/digilib-ext.zip">digilib-ext.zip</a> package) <ul> <li> <b>concurrent.jar</b> from Doug Lea's <a href="http://gee.cs.oswego.edu/dl/classes/EDU/oswego/cs/dl/util/concurrent/intro.html">util.concurrent library</a> (see <a href="http://gee.cs.oswego.edu/dl/">http://gee.cs.oswego.edu/dl/</a>). </li> <li> <b>log4j.jar</b> from the <a href="http://logging.apache.org/log4j/docs/download.html">Log4J library</a> (see <a href="http://logging.apache.org">http://logging.apache.org</a>) </li> <li> <b>jai_imageio.jar</b> (and its native libraries) with JDK >= 1.4, from the <a href="http://java.sun.com/products/java-media/jai/current.html">Java Advanced Imaging Image-IO Tools</a> (see <a href="http://java.sun.com/products/java-media/jai/index.jsp">http://java.sun.com/products/java-media/jai/</a>) </li> <li> <b>jai_core.jar, jai_codec.jar</b> if you want to use the JAIDocuImage implementation, from the <a href="http://java.sun.com/products/java-media/jai/current.html">Java Advanced Imaging API</a> (see <a href="http://java.sun.com/products/java-media/jai/index.jsp">http://java.sun.com/products/java-media/jai/</a>) </li> <li> <b>batik-*.jar</b> if you want to use the Raster servlet, from the <a href="http://www.apache.org/dyn/closer.cgi/xml/batik">Apache Batik library</a> (see <a href="http://xml.apache.org/batik/">http://xml.apache.org/batik/</a>) </li> <li> <b>jena.jar</b> from the <a href="http://www.hpl.hp.com/semweb/jena1.htm">JENA RDF library version 1.6.1</a> (see <a href="http://jena.sourceforge.net/">http://jena.sourceforge.net/</a>) </li> </ul> </ul> <h1>Installation</h1> <h2>On Linux/Unix</h2> <ol> <li>Make shure the Java JDK is installed (a JRE won't do).</li> <li>Create a base directory for digilib (the default used here is <code>/docuserver</code>) and for the web interface (<code>/docuserver/www</code>).</li> <li>Unpack the <b>digilib-core.zip</b> package in the web interface directory (<code>/docuserver/www</code>). This will create the digilib directory <code>digitallibrary</code>.</li> <li>Install the auxiliary Java libraries in <code>digitallibrary/WEB-INF/lib</code>. (Or just unpack the <b>digilib-ext.zip</b> package there.)</li> <li>Unpack Jakarta Tomcat 5.0.29 in <code>/docuserver</code> This should produce a directory <code>/docuserver/jakarta-tomcat-5.0.29</code>. Create a link <code>/docuserver/tomcat</code> to the new 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 installs digilib in the default Tomcat instance 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> </ol> <h2>On Windows (quick install)</h2> <ol> <li>Set the following Environment Variables:<br /> <code>CATALINA_HOME = C:\jakarta-tomcat-4.1.24</code> (or similar)<br /> <code>JAVA_HOME = C:\j2sdk</code> (or similar) </li> <li> Start Tomcat server: Open a console window (start <code>cmd.exe</code>).<br /> Type: <code>%CATALINA_HOME%\bin\startup</code> </li> <li> Try the following URL in your browser: <code>http://localhost:8080</code> or <code>http://127.0.0.1:8080</code> </li> <li> You should now be able to see the Tomcat opening screen: <em>If you're seeing this page via a web browser, it means you've setup Tomcat successfully. Congratulations!</em> </li> <li> Shut it down again: In the console window type <code>%CATALINA_HOME%\bin\shutdown</code>. </li> <li> Extract the <b>diglib-core.zip</b> package, possibly to <code>C:\docuserver</code>. </li> <li> Install the auxiliary Java libraries in <code>digitallibrary\WEB-INF\lib</code>. (Or just unpack the <b>digilib-ext.zip</b> package there.) </li> <li> Modify the following configuration files according to your paths (as in the "On Linux" section): <br> For tomcat <ul> <li><code>C:\jakarta-tomcat-4.1.24\conf\server.xml</code></li> <li><code>C:\jakarta-tomcat-4.1.24\conf\tomcat-users.xml</code></li> </ul> For digilib <ul> <li><code>C:\docuserver\digitallibrary\WEB-INF\digilib-config.xml</code></li> <li><code>C:\docuserver\digitallibrary\WEB-INF\digilib-auth.xml</code></li> </ul> In the <code>alcatraz-win-conf.zip</code> package you can find prepared configuration files with the following default values: <ul> <li>The image file directory is <code>C:\bilder</code>. </li> <li>The username for viewing image files is <code>digilib</code>.</li> <li>The password for viewing image files is <code>digilib</code>.</li> <li>The digilib server runs on Port <code>9090</code>.</li> </ul> </li> <li> Now you can restart the Tomcat server: <code>http://localhost:9090</code> or <code>http://127.0.0.1:9090</code>. </li> <li> Watch the images: <a href="http://localhost:9090/docuserver/digitallibrary/digilib.jsp">http://localhost:9090/docuserver/digitallibrary/digilib.jsp</a> </li> </ol> <h1>Configuration</h1> <h2>Tomcat</h2> <h3>catalina.sh / catalina.bat</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>or, on Windows<p> <pre> set CATALINA_HOME=C:\jakarta-tomcat-4.1.24 set JAVA_HOME=C:\j2sdk </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> <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> <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>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>digilib-config.xml</h3> <p>The main configuration for digilib is <code>digilib-config.xml</code>. It's normally in the <code>WEB-INF</code> directory in the webapp. (If you really need another location you can define it in the <code>config-file</code> init-parameter to the servlet)</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> <!-- 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. The authoritative directory with the high-resolution images is first in list. --> <parameter name="basedir-list" value=<b>"/docuserver/images:/docuserver/scaled/small"</b> /> <!-- 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> </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 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.</p> <p>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.</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> <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>robcast@mail.berlios.de</address> <!-- hhmts start -->Last modified: Tue Nov 2 13:14:57 CET 2004 <!-- hhmts end --> </body> </html>