323
+ − 1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
+ − 2 <html>
+ − 3 <head>
+ − 4 <title>Installation of digilib</title>
+ − 5 </head>
+ − 6
+ − 7 <body>
+ − 8 <h1>What you need to install digilib</h1>
+ − 9
+ − 10 <ul>
+ − 11 <li>
+ − 12 <a href="http://java.sun.com/downloads/index.html" >Java JDK</a> >1.2 (preferred 1.4 and up)
+ − 13 </li>
+ − 14
+ − 15 <li>
+ − 16 <a href="http://jakarta.apache.org/tomcat/index.html" >Jakarta
+ − 17 Tomcat</a> version 4 or later (preferred 4.1 and up) from
+ − 18 <a href="http://jakarta.apache.org">http://jakarta.apache.org</a>
+ − 19 </li>
+ − 20
+ − 21 <li>The digilib distribution package <a href="http://download.berlios.de/digilib/digilib-core.zip"><b>digilib-core.zip</b></a> (from
+ − 22 <a href="http://developer.berlios.de">http://developer.berlios.de</a>)
+ − 23
+ − 24 </li>
+ − 25
+ − 26 <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)
+ − 27 <ul>
+ − 28 <li>
+ − 29 <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>).
+ − 30 </li>
+ − 31
+ − 32 <li>
+ − 33 <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>)
+ − 34 </li>
+ − 35
+ − 36 <li>
+ − 37 <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>)
+ − 38 </li>
+ − 39
+ − 40 <li>
+ − 41 <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>)
+ − 42 </li>
+ − 43
+ − 44 <li>
+ − 45 <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>)
+ − 46 </li>
+ − 47
+ − 48 <li>
+ − 49 <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>)
+ − 50 </li>
+ − 51 </ul>
+ − 52 </ul>
+ − 53
+ − 54 <h1>Installation</h1>
+ − 55
+ − 56 <h2>On Linux/Unix</h2>
+ − 57
+ − 58 <ol>
+ − 59 <li>Make shure the Java JDK is installed (a JRE won't do).</li>
+ − 60
+ − 61 <li>Create a base directory for digilib (the default used here is
+ − 62 <code>/docuserver</code>) and for the web interface
+ − 63 (<code>/docuserver/www</code>).</li>
+ − 64
+ − 65 <li>Unpack the <b>digilib-core.zip</b> package in the web
+ − 66 interface directory (<code>/docuserver/www</code>). This will create
+ − 67 the digilib directory <code>digitallibrary</code>.</li>
+ − 68
+ − 69 <li>Install the auxiliary Java libraries in
+ − 70 <code>digitallibrary/WEB-INF/lib</code>. (Or just unpack the
+ − 71 <b>digilib-ext.zip</b> package there.)</li>
+ − 72
+ − 73 <li>Unpack Jakarta Tomcat 5.0.29 in <code>/docuserver</code> This should
+ − 74 produce a directory <code>/docuserver/jakarta-tomcat-5.0.29</code>. Create a
+ − 75 link <code>/docuserver/tomcat</code> to the new directory.</li>
+ − 76
+ − 77 <li>Create a link from the digilib directory into the Tomcat webapps
+ − 78 directory <code>/docuserver/tomcat/webapps</code> (type <code>ln -s
+ − 79 /docuserver/www/digitallibrary /docuserver/tomcat/webapps/</code>) This installs
+ − 80 digilib in the default Tomcat instance running on port 8080 as
+ − 81 <code>http://myserver:8080/digitallibrary/</code>.</li>
+ − 82
+ − 83 <li>Adjust the path to the JDK and its options in
+ − 84 <code>catalina.sh</code> (in the directory
+ − 85 <code>/docuserver/tomcat/bin</code>, see below for details)</li>
+ − 86 </ol>
+ − 87
+ − 88
+ − 89 <h2>On Windows (quick install)</h2>
+ − 90
+ − 91 <ol>
+ − 92 <li>Set the following Environment Variables:<br />
+ − 93 <code>CATALINA_HOME = C:\jakarta-tomcat-4.1.24</code> (or similar)<br />
+ − 94 <code>JAVA_HOME = C:\j2sdk</code> (or similar)
+ − 95 </li>
+ − 96
+ − 97 <li>
+ − 98 Start Tomcat server: Open a console window (start <code>cmd.exe</code>).<br />
+ − 99 Type: <code>%CATALINA_HOME%\bin\startup</code>
+ − 100 </li>
+ − 101
+ − 102 <li>
+ − 103 Try the following URL in your browser:
+ − 104 <code>http://localhost:8080</code> or
+ − 105 <code>http://127.0.0.1:8080</code>
+ − 106 </li>
+ − 107
+ − 108 <li>
+ − 109 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>
+ − 110 </li>
+ − 111
+ − 112 <li>
+ − 113 Shut it down again: In the console window type <code>%CATALINA_HOME%\bin\shutdown</code>.
+ − 114 </li>
+ − 115
+ − 116 <li>
+ − 117 Extract the <b>diglib-core.zip</b> package, possibly to <code>C:\docuserver</code>.
+ − 118 </li>
+ − 119
+ − 120 <li>
+ − 121 Install the auxiliary Java libraries in <code>digitallibrary\WEB-INF\lib</code>.
+ − 122 (Or just unpack the <b>digilib-ext.zip</b> package there.)
+ − 123 </li>
+ − 124
+ − 125 <li>
+ − 126 Modify the following configuration files according to your paths (as in the "On Linux" section):
+ − 127 <br>
+ − 128 For tomcat
+ − 129 <ul>
+ − 130 <li><code>C:\jakarta-tomcat-4.1.24\conf\server.xml</code></li>
+ − 131 <li><code>C:\jakarta-tomcat-4.1.24\conf\tomcat-users.xml</code></li>
+ − 132 </ul>
+ − 133 For digilib
+ − 134 <ul>
+ − 135 <li><code>C:\docuserver\digitallibrary\WEB-INF\digilib-config.xml</code></li>
+ − 136 <li><code>C:\docuserver\digitallibrary\WEB-INF\digilib-auth.xml</code></li>
+ − 137 </ul>
+ − 138 In the <code>alcatraz-win-conf.zip</code> package you can find
+ − 139 prepared configuration files with the following default values:
+ − 140 <ul>
+ − 141 <li>The image file directory is <code>C:\bilder</code>. </li>
+ − 142 <li>The username for viewing image files is <code>digilib</code>.</li>
+ − 143 <li>The password for viewing image files is <code>digilib</code>.</li>
+ − 144 <li>The digilib server runs on Port <code>9090</code>.</li>
+ − 145 </ul>
+ − 146 </li>
+ − 147
+ − 148 <li>
+ − 149 Now you can restart the Tomcat server: <code>http://localhost:9090</code> or
+ − 150 <code>http://127.0.0.1:9090</code>.
+ − 151 </li>
+ − 152
+ − 153 <li>
+ − 154 Watch the images:
+ − 155 <a href="http://localhost:9090/docuserver/digitallibrary/digilib.jsp">http://localhost:9090/docuserver/digitallibrary/digilib.jsp</a>
+ − 156 </li>
+ − 157 </ol>
+ − 158
+ − 159
+ − 160 <h1>Configuration</h1>
+ − 161
+ − 162 <h2>Tomcat</h2>
+ − 163
+ − 164 <h3>catalina.sh / catalina.bat</h3>
+ − 165
+ − 166 <p>The file <code>catalina.sh</code> (in <code>/docuserver/tomcat/bin</code>
+ − 167 can be modified to provide the path to the JDK and runtime options
+ − 168 for the Java VM. Somewhere at the beginning of the file you can put two lines
+ − 169 like this:</p>
+ − 170
+ − 171 <pre>
+ − 172 export JAVA_HOME=/usr/local/lib/IBMJava2-14
+ − 173 export CATALINA_OPTS="-mx512m"
+ − 174 </pre>
+ − 175
+ − 176 <p>or, on Windows<p>
+ − 177
+ − 178 <pre>
+ − 179 set CATALINA_HOME=C:\jakarta-tomcat-4.1.24
+ − 180 set JAVA_HOME=C:\j2sdk
+ − 181 </pre>
+ − 182
+ − 183 <p>Adjust the <code>JAVA_HOME</code> path to point to your Java JDK
+ − 184 installation directory. You can adjust the memory used by the Java VM
+ − 185 with the <code>-mx</code> option.</p>
+ − 186
+ − 187
+ − 188 <h3>tomcat-users.xml</h3>
+ − 189
+ − 190 <p>All passwords and usernames have to be set up in the file
+ − 191 <code>tomcat-users.xml</code> in <code>/docuserver/tomcat/conf</code> if you
+ − 192 want to use authentication in digilib. The file looks like this:</p>
+ − 193
+ − 194 <pre>
+ − 195 <tomcat-users>
+ − 196 <user name="tomcat" password="tomcat" roles="tomcat" />
+ − 197 <user name="role1" password="tomcat" roles="role1" />
+ − 198 <user name="both" password="tomcat" roles="tomcat,role1" />
+ − 199 </tomcat-users>
+ − 200 </pre>
+ − 201
+ − 202 <p>A user is identified by a <code>name</code> and
+ − 203 <code>password</code>. These two elements have to be entered in a
+ − 204 authentication form presented by the browser when accessing a
+ − 205 restricted resource. A user can have one or more
+ − 206 <code>roles</code>. These roles will be used by digilib to decide if
+ − 207 an authenticated user is allowed to access a document (see
+ − 208 <code>digilib-auth.xml</code> below).</p>
+ − 209
+ − 210 <p>If you want to use the webinterface to configure Tomcat, you have to
+ − 211 add administrational account with the roles <code>admin</code> and
+ − 212 <code>manager</code>.</p>
+ − 213
+ − 214 <p>tomcat has to be restarted before changes to
+ − 215 <code>tomcat-users.xml</code> have effect!</p>
+ − 216
+ − 217
+ − 218 <h2>Digilib</h2>
+ − 219
+ − 220 <h3>digilib-config.xml</h3>
+ − 221
+ − 222 <p>The main configuration for digilib is
+ − 223 <code>digilib-config.xml</code>. It's normally in the
+ − 224 <code>WEB-INF</code> directory in the webapp. (If you really need
+ − 225 another location you can define it in the <code>config-file</code>
+ − 226 init-parameter to the servlet)</p>
+ − 227
+ − 228 <p>In the configuration file you can set several paths and
+ − 229 options. The file looks like this:</p>
+ − 230
+ − 231 <pre>
+ − 232 <!-- Digilib servlet config file -->
+ − 233
+ − 234 <digilib-config>
+ − 235 <!-- Image to be sent to indicate general failure. -->
+ − 236 <parameter name="error-image" value=<b>"/docuserver/images/icons/broken.gif"</b> />
+ − 237
+ − 238 <!-- Image to be sent to indicate authorization failure. -->
+ − 239 <parameter name="denied-image" value=<b>"/docuserver/images/icons/alert.red.gif"</b> />
+ − 240
+ − 241 <!-- List of directories where images are searched.
+ − 242 The authoritative directory with the high-resolution images
+ − 243 is first in list. -->
+ − 244 <parameter name="basedir-list" value=<b>"/docuserver/images:/docuserver/scaled/small"</b> />
+ − 245
+ − 246 <!-- Java class to use for image operations -->
+ − 247 <parameter name="docuimage-class" value="digilib.image.JAIDocuImage" />
+ − 248
+ − 249 <!-- mimimum amount of scaling done with antialiasing -->
+ − 250 <parameter name="subsample-minimum" value="2"/>
+ − 251
+ − 252 <!-- default interpolation quality (0=worst) -->
+ − 253 <parameter name="default-quality" value="1"/>
+ − 254
+ − 255 <!-- is sending whole image files with mo=file allowed? -->
+ − 256 <parameter name="sendfile-allowed" value="true" />
+ − 257
+ − 258 <!-- the a maximum size of any sent image. (0 means no limit) -->
+ − 259 <parameter name="max-image-size" value="0" />
+ − 260
+ − 261 <!-- use safe but slow directory indexing -->
+ − 262 <parameter name="safe-dir-index" value="false" />
+ − 263
+ − 264 <!-- number of working threads -->
+ − 265 <parameter name="worker-threads" value="2" />
+ − 266
+ − 267 <!-- Restrict access to authorized users.
+ − 268 User authentication and roles are provided by the servlet container
+ − 269 (see tomcat-users.xml).
+ − 270 Authorization for resources (directories) is evaluated by the servlet
+ − 271 (see auth-file). -->
+ − 272 <parameter name="use-authorization" value="true"/>
+ − 273
+ − 274 <!-- Location of XML file with authorization requirements. -->
+ − 275 <parameter name="auth-file" value="digilib-auth.xml"/>
+ − 276
+ − 277 <!-- Part of URL to indicate authenticated access to Tomcat. -->
+ − 278 <parameter name="auth-url-path" value="authenticated/"/>
+ − 279
+ − 280 <!-- use mapping of "virtual directories" to real directories on the server --
+ − 281 >
+ − 282 <parameter name="use-mapping" value="false"/>
+ − 283
+ − 284 <!-- location of XML mapping file -->
+ − 285 <parameter name="mapping-file" value="digilib-map.xml"/>
+ − 286
+ − 287 <!-- location of logger config file -->
+ − 288 <parameter name="log-config-file" value="log4j-config.xml"/>
+ − 289 </digilib-config>
+ − 290 </pre>
+ − 291
+ − 292 <p>You have to adjust the <code>basedir-list</code> parameter to the
+ − 293 directories where your images are installed. You need only one
+ − 294 directory if you don't provide prescaled low resolution versions of your
+ − 295 images. The directory with the high-resolution images must be the
+ − 296 first entry in the list.</p>
+ − 297
+ − 298 <p>You can supply your own icons for the "error" and
+ − 299 "access denied" messages by the servlet. Standard images
+ − 300 will be used if these parameters are undefined.</p>
+ − 301
+ − 302 <p>You can specify the Java toolkit implementation with the
+ − 303 <code>docuimage-class</code> parameter. The
+ − 304 <code>ImageLoaderDocuImage</code> might give best performance but
+ − 305 works only with JDK 1.4 and up. <code>JAIDocuImage</code> works with
+ − 306 JDK 1.3 and up.</p>
+ − 307
+ − 308
+ − 309 <h3>digilib-auth.xml</h3>
+ − 310
+ − 311 <p>The digilib access authorization is defined in the file defined by
+ − 312 the <code>auth-file</code> parameter (usually
+ − 313 <code>digilib-auth.xml</code> in <code>WEB-INF</code>). </p>
+ − 314
+ − 315 <p>The file has two parts <code>diglib-paths</code> and
+ − 316 <code>diglib-addresses</code>. It looks like this:</p>
+ − 317
+ − 318 <pre>
+ − 319 <auth-config>
+ − 320
+ − 321 <digilib-paths>
+ − 322 <!--
+ − 323 A user must supply one of the roles under "role"
+ − 324 to access the directory "name".
+ − 325 Roles under "role" must be separated by comma only (no spaces).
+ − 326 -->
+ − 327 <path name="histast/eastwood-collection" role="eastwood-coll" />
+ − 328 <path name="ptolemaios_geo" role="ptolemaios-geo" />
+ − 329 </digilib-paths>
+ − 330
+ − 331 <digilib-addresses>
+ − 332 <!--
+ − 333 A computer with an ip address that matches "ip"
+ − 334 is automatically granted all roles under "role".
+ − 335 The ip address is matched from the left (in full quads).
+ − 336 Roles under "role" must be separated by comma only (no spaces).
+ − 337 -->
+ − 338 <address ip="127" role="local" />
+ − 339 <address ip="130.92.68" role="eastwood-coll,ptolemaios-geo" />
+ − 340 <address ip="130.92.151" role="ALL" />
+ − 341 </digilib-addresses>
+ − 342
+ − 343 </auth-config>
+ − 344 </pre>
+ − 345
+ − 346 <p><code>diglib-paths</code> defines restricted directories and
+ − 347 the roles needed for access. The roles are defined with the users in
+ − 348 <code>tomcat-users.xml</code> (see above). All subdirectories of the
+ − 349 given directories have the same restrictions. All directories not
+ − 350 listed here (and not subdirectories of listed directories) are freely
+ − 351 accessible.</p>
+ − 352
+ − 353 <p><code>diglib-addresses</code> defines hosts or networks of
+ − 354 computers that are automatically authenticated without username and
+ − 355 password. Hosts can be assigned roles. The special keyword <code>ALL</code>
+ − 356 authorizes for everything. If the role assigned to the computer is not
+ − 357 sufficient to access a resource the user will be asked for username
+ − 358 and password.</p>
+ − 359
+ − 360
+ − 361
+ − 362 <hr>
+ − 363 <address>robcast@mail.berlios.de</address>
+ − 364 <!-- hhmts start -->Last modified: Tue Nov 2 13:14:57 CET 2004 <!-- hhmts end -->
+ − 365 </body> </html>
