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