Mercurial > hg > digilib-old

comparison docu/installation.html @ 22:37eae12d4148

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Initial revision
author robcast
date Thu, 17 Jan 2002 15:31:01 +0100
parents
children dd49040ae5a5
comparison
equal deleted inserted replaced
20:d407cb901df4 22:37eae12d4148
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 &gt;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
14 http://jakarta.apache.org</li>
15 <li>The digilib distribution packages (from
16 http://penelope.unibe.ch/docuserver/digitallibrary/dist/)
17 <ul>
18 <li>digilib scripts and servlets package
19 <a href="http://penelope.unibe.ch/docuserver/digitallibrary/dist/digilib-core.zip"><code>digilib-core.zip</code></a></li>
20 <li>digilib configuration files for tomcat 4 package
21 <a href="http://penelope.unibe.ch/docuserver/digitallibrary/dist/digilib-tomconf.zip"><code>digilib-tomconf.zip</code></a></li>
22 <li>digilib external libraries package <a href="http://penelope.unibe.ch/docuserver/digitallibrary/dist/digilib-ext.zip"><code>digilib-ext.zip</code></a>
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 &lt;!-- Digilib Server Configuration File --&gt;
120
121 &lt;Server port="8005" shutdown="SHUTDOWN" debug="0"&gt;
122
123 &lt;!-- Define an Apache-Connector Service --&gt;
124 &lt;Service name="Tomcat-Docuserver"&gt;
125
126 &lt;!-- Define a non-SSL HTTP/1.1 Connector on port 8080 --&gt;
127 &lt;Connector className="org.apache.catalina.connector.http.HttpConnector"
128 port=<b>"8080"</b> minProcessors="5" maxProcessors="75"
129 acceptCount="10" debug="0" connectionTimeout="60000"/&gt;
130
131 &lt;!-- Replace "localhost" with what your Apache "ServerName" is set to --&gt;
132 &lt;Engine className="org.apache.catalina.connector.warp.WarpEngine"
133 name="Apache" debug="1" appBase="webapps" defaultHost=<b>"hera.unibe.ch"</b>&gt;
134
135 &lt;!-- Global logger unless overridden at lower levels --&gt;
136 &lt;Logger className="org.apache.catalina.logger.FileLogger"
137 prefix="apache_log." suffix=".txt"
138 timestamp="true"/&gt;
139
140 &lt;!-- Define the default virtual host. Hostname must match the engine's. --&gt;
141 &lt;Host name=<b>"hera.unibe.ch"</b> debug="0" appBase=<b>"/docuserver/www"</b>&gt;
142
143 &lt;Context path="/docuserver/digitallibrary" docBase=<b>"/docuserver/www/digitallibrary"</b> debug="0" reloadable="false"&gt;
144 &lt;/Context&gt;
145
146 &lt;/Host&gt;
147
148 &lt;!-- Because this Realm is here, an instance will be shared globally --&gt;
149 &lt;Realm className="org.apache.catalina.realm.MemoryRealm" /&gt;
150
151 &lt;/Engine&gt;
152
153 &lt;/Service&gt;
154
155 &lt;/Server&gt;
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 &lt;tomcat-users&gt;
181 &lt;user name="tomcat" password="tomcat" roles="tomcat" /&gt;
182 &lt;user name="role1" password="tomcat" roles="role1" /&gt;
183 &lt;user name="both" password="tomcat" roles="tomcat,role1" /&gt;
184 &lt;/tomcat-users&gt;
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 &lt;!-- parameters to the servlet --&gt;
213 &lt;init-param&gt;
214 &lt;param-name&gt;config-file&lt;/param-name&gt;
215 &lt;param-value&gt;
216 <b>/docuserver/www/digitallibrary/WEB-INF/digilib-config.xml</b>
217 &lt;/param-value&gt;
218 &lt;/init-param&gt;
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 &lt;!-- Digilib servlet config file --&gt;
238
239 &lt;digilib-config&gt;
240 &lt;parameter name="debug-level" value="0" /&gt;
241
242 &lt;!-- Image to be sent to indicate general failure. --&gt;
243 &lt;parameter name="error-image" value=<b>"/docuserver/images/icons/broken.gif"</b> /&gt;
244
245 &lt;!-- Image to be sent to indicate authorization failure. --&gt;
246 &lt;parameter name="denied-image" value=<b>"/docuserver/images/icons/alert.red.gif"</b> /&gt;
247
248 &lt;!-- List of directories where images are searched.
249 Directories with low-resolution images are first in list. --&gt;
250 &lt;parameter name="basedir-list" value=<b>"/docuserver/scaled/small:/docuserver/images:/docuserver/scans/quellen"</b> /&gt;
251
252 &lt;!-- 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). --&gt;
257 &lt;parameter name="use-authorization" value="true" /&gt;
258
259 &lt;!-- URL location of XML file with authorization requirements. --&gt;
260 &lt;parameter name="auth-file" value=<b>"/docuserver/www/digitallibrary/WEB-INF/digilib-auth.xml"</b> /&gt;
261
262 &lt;!-- Part of URL to indicate authenticated access to Tomcat. --&gt;
263 &lt;parameter name="auth-url-path" value="authenticated/" /&gt;
264 &lt;/digilib-config&gt;
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 &quot;error&quot; and
273 &quot;access denied&quot; 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 &lt;auth-config&gt;
291
292 &lt;digilib-paths&gt;
293 &lt;!--
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 --&gt;
298 &lt;path name="histast/eastwood-collection" role="eastwood-coll" /&gt;
299 &lt;path name="ptolemaios_geo" role="ptolemaios-geo" /&gt;
300 &lt;/digilib-paths&gt;
301
302 &lt;digilib-addresses&gt;
303 &lt;!--
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 --&gt;
309 &lt;address ip="127" role="local" /&gt;
310 &lt;address ip="130.92.68" role="eastwood-coll,ptolemaios-geo" /&gt;
311 &lt;address ip="130.92.151" role="ALL" /&gt;
312 &lt;/digilib-addresses&gt;
313
314 &lt;/auth-config&gt;
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>
335 <!-- hhmts start --> Last modified: Wed Jan 16 18:20:57 CET 2002 <!-- hhmts end -->
336 </body> </html>