Mercurial > hg > digilib-old
comparison docu/installation.html @ 22:37eae12d4148
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 >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 <!-- 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> | |
335 <!-- hhmts start --> Last modified: Wed Jan 16 18:20:57 CET 2002 <!-- hhmts end --> | |
336 </body> </html> |