Mercurial > hg > digilib-old

comparison webapp/doc/digilib_install.html @ 903:7779b37d1d05

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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 client/doc/digilib_install.html@c70a5016fdc5
children a00114a0c957
comparison
equal deleted inserted replaced
902:89ba3ffcf552 903:7779b37d1d05
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> &gt;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 &quot;On Linux&quot; 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 &lt;tomcat-users&gt;
196 &lt;user name="tomcat" password="tomcat" roles="tomcat" /&gt;
197 &lt;user name="role1" password="tomcat" roles="role1" /&gt;
198 &lt;user name="both" password="tomcat" roles="tomcat,role1" /&gt;
199 &lt;/tomcat-users&gt;
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 &lt;!-- Digilib servlet config file --&gt;
233
234 &lt;digilib-config&gt;
235 &lt;!-- Image to be sent to indicate general failure. --&gt;
236 &lt;parameter name=&quot;error-image&quot; value=<b>&quot;/docuserver/images/icons/broken.gif&quot;</b> /&gt;
237
238 &lt;!-- Image to be sent to indicate authorization failure. --&gt;
239 &lt;parameter name=&quot;denied-image&quot; value=<b>&quot;/docuserver/images/icons/alert.red.gif&quot;</b> /&gt;
240
241 &lt;!-- List of directories where images are searched.
242 The authoritative directory with the high-resolution images
243 is first in list. --&gt;
244 &lt;parameter name=&quot;basedir-list&quot; value=<b>&quot;/docuserver/images:/docuserver/scaled/small&quot;</b> /&gt;
245
246 &lt;!-- Java class to use for image operations --&gt;
247 &lt;parameter name=&quot;docuimage-class&quot; value=&quot;digilib.image.JAIDocuImage&quot; /&gt;
248
249 &lt;!-- mimimum amount of scaling done with antialiasing --&gt;
250 &lt;parameter name=&quot;subsample-minimum&quot; value=&quot;2&quot;/&gt;
251
252 &lt;!-- default interpolation quality (0=worst) --&gt;
253 &lt;parameter name=&quot;default-quality&quot; value=&quot;1&quot;/&gt;
254
255 &lt;!-- is sending whole image files with mo=file allowed? --&gt;
256 &lt;parameter name=&quot;sendfile-allowed&quot; value=&quot;true&quot; /&gt;
257
258 &lt;!-- the a maximum size of any sent image. (0 means no limit) --&gt;
259 &lt;parameter name=&quot;max-image-size&quot; value=&quot;0&quot; /&gt;
260
261 &lt;!-- use safe but slow directory indexing --&gt;
262 &lt;parameter name=&quot;safe-dir-index&quot; value=&quot;false&quot; /&gt;
263
264 &lt;!-- number of working threads --&gt;
265 &lt;parameter name=&quot;worker-threads&quot; value=&quot;2&quot; /&gt;
266
267 &lt;!-- 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). --&gt;
272 &lt;parameter name=&quot;use-authorization&quot; value=&quot;true&quot;/&gt;
273
274 &lt;!-- Location of XML file with authorization requirements. --&gt;
275 &lt;parameter name=&quot;auth-file&quot; value=&quot;digilib-auth.xml&quot;/&gt;
276
277 &lt;!-- Part of URL to indicate authenticated access to Tomcat. --&gt;
278 &lt;parameter name=&quot;auth-url-path&quot; value=&quot;authenticated/&quot;/&gt;
279
280 &lt;!-- use mapping of &quot;virtual directories&quot; to real directories on the server --
281 &gt;
282 &lt;parameter name=&quot;use-mapping&quot; value=&quot;false&quot;/&gt;
283
284 &lt;!-- location of XML mapping file --&gt;
285 &lt;parameter name=&quot;mapping-file&quot; value=&quot;digilib-map.xml&quot;/&gt;
286
287 &lt;!-- location of logger config file --&gt;
288 &lt;parameter name=&quot;log-config-file&quot; value=&quot;log4j-config.xml&quot;/&gt;
289 &lt;/digilib-config&gt;
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 &quot;error&quot; and
299 &quot;access denied&quot; 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 &lt;auth-config&gt;
320
321 &lt;digilib-paths&gt;
322 &lt;!--
323 A user must supply one of the roles under &quot;role&quot;
324 to access the directory &quot;name&quot;.
325 Roles under &quot;role&quot; must be separated by comma only (no spaces).
326 --&gt;
327 &lt;path name=&quot;histast/eastwood-collection&quot; role=&quot;eastwood-coll&quot; /&gt;
328 &lt;path name=&quot;ptolemaios_geo&quot; role=&quot;ptolemaios-geo&quot; /&gt;
329 &lt;/digilib-paths&gt;
330
331 &lt;digilib-addresses&gt;
332 &lt;!--
333 A computer with an ip address that matches &quot;ip&quot;
334 is automatically granted all roles under &quot;role&quot;.
335 The ip address is matched from the left (in full quads).
336 Roles under &quot;role&quot; must be separated by comma only (no spaces).
337 --&gt;
338 &lt;address ip=&quot;127&quot; role=&quot;local&quot; /&gt;
339 &lt;address ip=&quot;130.92.68&quot; role=&quot;eastwood-coll,ptolemaios-geo&quot; /&gt;
340 &lt;address ip=&quot;130.92.151&quot; role=&quot;ALL&quot; /&gt;
341 &lt;/digilib-addresses&gt;
342
343 &lt;/auth-config&gt;
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>