|
22
|
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>Java JDK >1.2 (preferred 1.3)</li>
|
|
|
12 <li><a href="http://jakarta.apache.org/tomcat/index.html" >Jakarta
|
|
|
13 tomcat</a> version 4.0.1 from
|
|
27
|
14 <a href="http://jakarta.apache.org<" >http://jakarta.apache.org</a></li>
|
|
22
|
15 <li>The digilib distribution packages (from
|
|
27
|
16 <a href="http://developer.berlios.de" >http://developer.berlios.de</a>)
|
|
22
|
17 <ul>
|
|
|
18 <li>digilib scripts and servlets package
|
|
27
|
19 <a href="http://download.berlios.de/digilib/digilib-core-1.0.zip"><code>digilib-core.zip</code></a></li>
|
|
22
|
20 <li>digilib configuration files for tomcat 4 package
|
|
27
|
21 <a href="http://download.berlios.de/digilib/digilib-tomconf-1.0.zip"><code>digilib-tomconf.zip</code></a></li>
|
|
|
22 <li>digilib external libraries package <a href="http://download.berlios.de/digilib/digilib-ext-1.0.zip"><code>digilib-ext.zip</code></a>
|
|
22
|
23 (Not essential. Contains documentation to JAI 1.1.1 and Xerces
|
|
|
24 1.4.3)</li>
|
|
|
25 </ul>
|
|
|
26 </li>
|
|
|
27 </ul>
|
|
|
28
|
|
|
29 <h1>Installation</h1>
|
|
|
30
|
|
|
31 <h2>On Linux</h2>
|
|
|
32
|
|
|
33 <ol>
|
|
|
34 <li>Make shure Java JDK is installed</li>
|
|
|
35 <li>Create a base directory for docuserver (the default used here is
|
|
|
36 <code>/docuserver</code>) and for the web interface
|
|
|
37 (<code>/docuserver/www</code>).</li>
|
|
|
38 <li>Unpack the <code>digilib-core</code> package in the web
|
|
|
39 interface directory (<code>/docuserver/www</code>). This will create
|
|
|
40 the digilib directory <code>digitallibrary</code>.</li>
|
|
|
41 <li>(optional) Unpack the <code>digilib-ext</code> package in the
|
|
|
42 docuserver directory.</li>
|
|
|
43 <li>Unpack Jakarta tomcat 4.0.1 in <code>/opt</code> This should
|
|
|
44 produce a directory <code>/opt/jakarta-tomcat-4.0.1</code>. Create a
|
|
|
45 link <code>/opt/tomcat</code> to the new directory.</li>
|
|
|
46 <li>Unpack the configuration files package
|
|
|
47 <code>digilib-tomconf</code> in the tomcat directory.</li>
|
|
|
48 <li>Adjust hostname and HTML-base directory in the file
|
|
|
49 <code>server.xml</code> (in the directory
|
|
|
50 <code>/opt/tomcat/conf</code>, see below for details))</li>
|
|
|
51 <li>Adjust the path to the JDK and its options in
|
|
|
52 <code>catalina.sh</code> (in the directory
|
|
|
53 <code>/opt/tomcat/bin</code>, see below for details)</li>
|
|
|
54 <li>(optional) For SuSE Linux you can use the startup skript
|
|
|
55 <code>tomcat/bin/rctomcat</code>
|
|
|
56 to start and stop the tomcat server. Copy the script into
|
|
|
57 <code>/etc/init.d</code> as <code>tomcat</code> and set runlevel
|
|
|
58 links accordingly.</li>
|
|
|
59 <li>(optional) Set the tomcat directory and all files to be owned by
|
|
|
60 the user
|
|
|
61 <code>wwwrun</code> (or whatever your webserver runs) and use this
|
|
|
62 account to start the tomcat server.</li>
|
|
|
63 </ol>
|
|
|
64
|
|
|
65
|
|
|
66 <!--
|
|
|
67 <h2>Apache connector module</h2>
|
|
|
68
|
|
|
69 <p>digilib currently needs to be accessed through the Apache
|
|
|
70 webserver. There are two possible connectors for Apache and Tomcat4:
|
|
|
71 <code>mod_webapp</code> and <code>mod_jk</code>. Only
|
|
|
72 <code>mod_webapp</code> has been tested so far.</p>
|
|
|
73
|
|
|
74 <ol>
|
|
|
75 <li>Get the sources for <code>mod_webapp</code></li>
|
|
|
76 </ol>
|
|
|
77 -->
|
|
|
78
|
|
|
79 <h1>Configuration</h1>
|
|
|
80
|
|
|
81 <h2>Tomcat</h2>
|
|
|
82
|
|
|
83 <h3>catalina.sh</h3>
|
|
|
84
|
|
|
85 <p>The file <code>catalina.sh</code> (in <code>/opt/tomcat/bin</code>
|
|
|
86 has been modified to provide the path to the JDK and runtime options
|
|
|
87 for the Java VM. Somewhere at the beginning of the file are two lines
|
|
|
88 like this:</p>
|
|
|
89
|
|
|
90 <pre>
|
|
|
91 export JAVA_HOME=/usr/local/lib/IBMJava2-13
|
|
|
92 export CATALINA_OPTS="-mx512m"
|
|
|
93 </pre>
|
|
|
94
|
|
|
95 <p>Adjust the <code>JAVA_HOME</code> path to point to your Java JDK
|
|
|
96 installation directory. You can adjust the memory used by the Java VM
|
|
|
97 with the <code>-mx512m</code> option.</p>
|
|
|
98
|
|
|
99 <p>You can delete those two lines if you set these variables in your
|
|
|
100 shell before starting tomcat in that same shell. These lines are
|
|
|
101 needed if you want to use the startup script for linux mentioned
|
|
|
102 above.</p>
|
|
|
103
|
|
|
104
|
|
|
105 <h3>server.xml</h3>
|
|
|
106
|
|
|
107 <p>The environment of the tomcat server is configured in the file
|
|
|
108 <code>server.xml</code> in <code>/opt/tomcat/conf</code>. Extensive <a
|
|
|
109 href="http://jakarta.apache.org/tomcat/tomcat-4.0-doc/index.html">documentation
|
|
|
110 about all options</a> can by found on the webpages of the tomcat
|
|
|
111 project.</p>
|
|
|
112
|
|
|
113 <p>A minimal configuration file for running digilib is provided in the
|
|
|
114 <code>digilib-tomconf</code> package. For standard operation only a
|
|
|
115 few adjustments have to be made. The configuration file should look
|
|
|
116 like this:</p>
|
|
|
117
|
|
|
118 <pre>
|
|
|
119 <!-- Digilib Server Configuration File -->
|
|
|
120
|
|
|
121 <Server port="8005" shutdown="SHUTDOWN" debug="0">
|
|
|
122
|
|
|
123 <!-- Define an Apache-Connector Service -->
|
|
|
124 <Service name="Tomcat-Docuserver">
|
|
|
125
|
|
|
126 <!-- Define a non-SSL HTTP/1.1 Connector on port 8080 -->
|
|
|
127 <Connector className="org.apache.catalina.connector.http.HttpConnector"
|
|
|
128 port=<b>"8080"</b> minProcessors="5" maxProcessors="75"
|
|
|
129 acceptCount="10" debug="0" connectionTimeout="60000"/>
|
|
|
130
|
|
|
131 <!-- Replace "localhost" with what your Apache "ServerName" is set to -->
|
|
|
132 <Engine className="org.apache.catalina.connector.warp.WarpEngine"
|
|
|
133 name="Apache" debug="1" appBase="webapps" defaultHost=<b>"hera.unibe.ch"</b>>
|
|
|
134
|
|
|
135 <!-- Global logger unless overridden at lower levels -->
|
|
|
136 <Logger className="org.apache.catalina.logger.FileLogger"
|
|
|
137 prefix="apache_log." suffix=".txt"
|
|
|
138 timestamp="true"/>
|
|
|
139
|
|
|
140 <!-- Define the default virtual host. Hostname must match the engine's. -->
|
|
|
141 <Host name=<b>"hera.unibe.ch"</b> debug="0" appBase=<b>"/docuserver/www"</b>>
|
|
|
142
|
|
|
143 <Context path="/docuserver/digitallibrary" docBase=<b>"/docuserver/www/digitallibrary"</b> debug="0" reloadable="false">
|
|
|
144 </Context>
|
|
|
145
|
|
|
146 </Host>
|
|
|
147
|
|
|
148 <!-- Because this Realm is here, an instance will be shared globally -->
|
|
|
149 <Realm className="org.apache.catalina.realm.MemoryRealm" />
|
|
|
150
|
|
|
151 </Engine>
|
|
|
152
|
|
|
153 </Service>
|
|
|
154
|
|
|
155 </Server>
|
|
|
156 </pre>
|
|
|
157
|
|
|
158 <p>You can change the portnumber of your server to be something other
|
|
|
159 than <b>8080</b> in the <code>port</code> property. If you want to use the
|
|
|
160 default webserver port 80 you have to run tomcat as the root user (it
|
|
|
161 is less secure to do this!).</p>
|
|
|
162
|
|
|
163 <p>You have to change the occurences of <b>hera.unibe.ch</b> (in
|
|
|
164 the <code>defaultHost</code> and <code>name</code> properties) to your
|
|
|
165 hostname.</p>
|
|
|
166
|
|
|
167 <p>Then you can adjust the <b>/docuserver/www</b> path to the
|
|
|
168 directory where you installed the <code>digilib-core</code>
|
|
|
169 package. You should not change the <code>path</code> property but only
|
|
|
170 the <code>appBase</code> and <code>docBase</code> properties!</p>
|
|
|
171
|
|
|
172
|
|
|
173 <h3>tomcat-users.xml</h3>
|
|
|
174
|
|
|
175 <p>All passwords and usernames have to be set up in the file
|
|
|
176 <code>tomcat-users.xml</code> in <code>/opt/tomcat/conf</code> if you
|
|
|
177 want to use authentication in digilib. The file looks like this:</p>
|
|
|
178
|
|
|
179 <pre>
|
|
|
180 <tomcat-users>
|
|
|
181 <user name="tomcat" password="tomcat" roles="tomcat" />
|
|
|
182 <user name="role1" password="tomcat" roles="role1" />
|
|
|
183 <user name="both" password="tomcat" roles="tomcat,role1" />
|
|
|
184 </tomcat-users>
|
|
|
185 </pre>
|
|
|
186
|
|
|
187 <p>A user is identified by a <code>name</code> and
|
|
|
188 <code>password</code>. These two elements have to be entered in a
|
|
|
189 authentication form presented by the browser when accessing a
|
|
|
190 restricted resource. A user can have one or more
|
|
|
191 <code>roles</code>. These roles will be used by digilib to decide if
|
|
|
192 an authenticated user is allowed to access a document (see
|
|
|
193 <code>digilib-auth.xml</code> below).</p>
|
|
|
194
|
|
|
195 <p>tomcat has to be restarted before changes to
|
|
|
196 <code>tomcat-users.xml</code> have effect!</p>
|
|
|
197
|
|
|
198 <h2>Digilib</h2>
|
|
|
199
|
|
|
200 <h3>web.xml</h3>
|
|
|
201
|
|
|
202 <p>The deployment of the digilib servlets and JSPs is defined in the
|
|
|
203 file <code>web.xml</code> in the <code>WEB-INF</code> subdirectory of
|
|
|
204 the digilib directory
|
|
|
205 (<code>/docuserver/www/digitallibrary/WEB-INF</code>).</p>
|
|
|
206
|
|
|
207 <p>The only parameter you might have to adjust is the position of the
|
|
|
208 digilib configuration file. The parameter occurs twice in the file and
|
|
|
209 looks like this:</p>
|
|
|
210
|
|
|
211 <pre>
|
|
|
212 <!-- parameters to the servlet -->
|
|
|
213 <init-param>
|
|
|
214 <param-name>config-file</param-name>
|
|
|
215 <param-value>
|
|
|
216 <b>/docuserver/www/digitallibrary/WEB-INF/digilib-config.xml</b>
|
|
|
217 </param-value>
|
|
|
218 </init-param>
|
|
|
219 </pre>
|
|
|
220
|
|
|
221 <p>Change the path to where you installed the configuration files.</p>
|
|
|
222
|
|
|
223 <p>Make shure to change the parameter in both places! It is needed
|
|
|
224 both for the servlet and the JSP pages!</p>
|
|
|
225
|
|
|
226 <h3>digilib-config.xml</h3>
|
|
|
227
|
|
|
228 <p>The main configuration for digilib is
|
|
|
229 <code>digilib-config.xml</code>. It's position is defined by the
|
|
|
230 <code>config-file</code> init-parameter to the servlets (see
|
|
|
231 above).</p>
|
|
|
232
|
|
|
233 <p>In the configuration file you can set several paths and
|
|
|
234 options. The file looks like this:</p>
|
|
|
235
|
|
|
236 <pre>
|
|
|
237 <!-- Digilib servlet config file -->
|
|
|
238
|
|
|
239 <digilib-config>
|
|
|
240 <parameter name="debug-level" value="0" />
|
|
|
241
|
|
|
242 <!-- Image to be sent to indicate general failure. -->
|
|
|
243 <parameter name="error-image" value=<b>"/docuserver/images/icons/broken.gif"</b> />
|
|
|
244
|
|
|
245 <!-- Image to be sent to indicate authorization failure. -->
|
|
|
246 <parameter name="denied-image" value=<b>"/docuserver/images/icons/alert.red.gif"</b> />
|
|
|
247
|
|
|
248 <!-- List of directories where images are searched.
|
|
|
249 Directories with low-resolution images are first in list. -->
|
|
|
250 <parameter name="basedir-list" value=<b>"/docuserver/scaled/small:/docuserver/images:/docuserver/scans/quellen"</b> />
|
|
|
251
|
|
|
252 <!-- Restrict access to authorized users.
|
|
|
253 User authentication and roles are provided by the servlet container
|
|
|
254 (see tomcat-users.xml).
|
|
|
255 Authorization for resources (directories) is evaluated by the servlet
|
|
|
256 (see auth-file). -->
|
|
|
257 <parameter name="use-authorization" value="true" />
|
|
|
258
|
|
|
259 <!-- URL location of XML file with authorization requirements. -->
|
|
|
260 <parameter name="auth-file" value=<b>"/docuserver/www/digitallibrary/WEB-INF/digilib-auth.xml"</b> />
|
|
|
261
|
|
|
262 <!-- Part of URL to indicate authenticated access to Tomcat. -->
|
|
|
263 <parameter name="auth-url-path" value="authenticated/" />
|
|
|
264 </digilib-config>
|
|
|
265 </pre>
|
|
|
266
|
|
|
267 <p>You have to adjust the <code>basedir-list</code> parameter to the
|
|
|
268 directories where your images are installed. You need only one
|
|
|
269 directory if you do not have prescaled low resolution versions of your
|
|
|
270 images.</p>
|
|
|
271
|
|
|
272 <p>You can supply your own images for the "error" and
|
|
|
273 "access denied" messages by the servlet. Standard images
|
|
|
274 will be used if these parameters are undefined.</p>
|
|
|
275
|
|
|
276 <p>The <code>auth-file</code> parameter has to point to the
|
|
|
277 authorization configuration file (see below).</p>
|
|
|
278
|
|
|
279
|
|
|
280 <h3>digilib-auth.xml</h3>
|
|
|
281
|
|
|
282 <p>The digilib access authorization is defined in the file defined by
|
|
|
283 the <code>auth-file</code> parameter (usually
|
|
|
284 <code>digilib-auth.xml</code> in <code>WEB-INF</code>). </p>
|
|
|
285
|
|
|
286 <p>The file has two parts <code>diglib-paths</code> and
|
|
|
287 <code>diglib-addresses</code>. It looks like this:</p>
|
|
|
288
|
|
|
289 <pre>
|
|
|
290 <auth-config>
|
|
|
291
|
|
|
292 <digilib-paths>
|
|
|
293 <!--
|
|
|
294 A user must supply one of the roles under "role"
|
|
|
295 to access the directory "name".
|
|
|
296 Roles under "role" must be separated by comma only (no spaces).
|
|
|
297 -->
|
|
|
298 <path name="histast/eastwood-collection" role="eastwood-coll" />
|
|
|
299 <path name="ptolemaios_geo" role="ptolemaios-geo" />
|
|
|
300 </digilib-paths>
|
|
|
301
|
|
|
302 <digilib-addresses>
|
|
|
303 <!--
|
|
|
304 A computer with an ip address that matches "ip"
|
|
|
305 is automatically granted all roles under "role".
|
|
|
306 The ip address is matched from the left (in full quads).
|
|
|
307 Roles under "role" must be separated by comma only (no spaces).
|
|
|
308 -->
|
|
|
309 <address ip="127" role="local" />
|
|
|
310 <address ip="130.92.68" role="eastwood-coll,ptolemaios-geo" />
|
|
|
311 <address ip="130.92.151" role="ALL" />
|
|
|
312 </digilib-addresses>
|
|
|
313
|
|
|
314 </auth-config>
|
|
|
315 </pre>
|
|
|
316
|
|
|
317 <p><code>diglib-paths</code> defines restricted directories and
|
|
|
318 the roles needed for access. The roles are defined with the users in
|
|
|
319 <code>tomcat-users.xml</code> (see above). All subdirectories of the
|
|
|
320 given directories have the same restrictions. All directories not
|
|
|
321 listed here (and not subdirectories of listed directories) are freely
|
|
|
322 accessible.</p>
|
|
|
323
|
|
|
324 <p><code>diglib-addresses</code> defines hosts or networks of
|
|
|
325 computers that are automatically authenticated without username and
|
|
|
326 password. Hosts can be assigned roles. The special keyword <code>ALL</code>
|
|
|
327 authorizes for everything. If the role assigned to the computer is not
|
|
|
328 sufficient to access a resource the user will be asked for username
|
|
|
329 and password.</p>
|
|
|
330
|
|
|
331
|
|
|
332
|
|
|
333 <hr>
|
|
|
334 <address>robert.casties@philo.unibe.ch</address>
|
|
27
|
335 <!-- hhmts start --> Last modified: Thu Jan 17 19:12:01 CET 2002 <!-- hhmts end -->
|
|
22
|
336 </body> </html>
|
