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