Mercurial > hg > digilib-old

comparison docu/installation.html @ 108:ffc7d9138397

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Updated for alcatraz/digilib 1.3 and up.
author robcast
date Tue, 13 May 2003 23:40:34 +0200
parents dd49040ae5a5
children 28e449fa185c
comparison
equal deleted inserted replaced
106:19edc2593b88 108:ffc7d9138397
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN"> 1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
2 <html> 2 <html>
3 <head> 3 <head>
4 <title>Installation of digilib</title> 4 <title>Installation of alcatraz/digilib</title>
5 </head> 5 </head>
6 6
7 <body> 7 <body>
8 <h1>What you need to install digilib</h1> 8 <h1>What you need to install digilib</h1>
9 9
10 <ul> 10 <ul>
11 <li>Java JDK &gt;1.2 (preferred 1.3)</li> 11 <li>Java JDK &gt;1.2 (preferred 1.4 and up)</li>
12
12 <li><a href="http://jakarta.apache.org/tomcat/index.html" >Jakarta 13 <li><a href="http://jakarta.apache.org/tomcat/index.html" >Jakarta
13 tomcat</a> version 4.0.1 from 14 Tomcat</a> version 4 or later (preferred 4.1 and up) from
14 <a href="http://jakarta.apache.org<" >http://jakarta.apache.org</a></li> 15 <a href="http://jakarta.apache.org<" >http://jakarta.apache.org</a></li>
16
15 <li>The digilib distribution packages (from 17 <li>The digilib distribution packages (from
16 <a href="http://developer.berlios.de" >http://developer.berlios.de</a>) 18 <a href="http://developer.berlios.de" >http://developer.berlios.de</a>)
17 <ul> 19 <ul>
18 <li>digilib scripts and servlets package 20 <li>alcatraz/digilib scripts and servlets package
19 <a href="http://download.berlios.de/digilib/digilib-core-1.0.zip"><code>digilib-core.zip</code></a></li> 21 <a href="http://download.berlios.de/digilib/alcatraz-core-0.3.zip"><code>alcatraz-core.zip</code></a></li>
20 <li>digilib configuration files for tomcat 4 package 22 <li>digilib configuration files for tomcat 4 package
21 <a href="http://download.berlios.de/digilib/digilib-tomconf-1.0.zip"><code>digilib-tomconf.zip</code></a></li> 23 <a href="http://download.berlios.de/digilib/alcatraz-tomconf-0.1.zip"><code>alcatraz-tomconf.zip</code></a> (Not essential)</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>
23 (Not essential. Contains documentation to JAI 1.1.1 and Xerces
24 1.4.3)</li>
25 </ul> 24 </ul>
26 </li> 25 </li>
27 </ul> 26 </ul>
28 27
29 <h1>Installation</h1> 28 <h1>Installation</h1>
30 29
31 <h2>On Linux</h2> 30 <h2>On Linux</h2>
32 31
33 <ol> 32 <ol>
34 <li>Make shure Java JDK is installed</li> 33 <li>Make shure the Java JDK is installed (a JRE won't do).</li>
34
35 <li>Create a base directory for docuserver (the default used here is 35 <li>Create a base directory for docuserver (the default used here is
36 <code>/docuserver</code>) and for the web interface 36 <code>/docuserver</code>) and for the web interface
37 (<code>/docuserver/www</code>).</li> 37 (<code>/docuserver/www</code>).</li>
38 <li>Unpack the <code>digilib-core</code> package in the web 38
39 <li>Unpack the <code>alcatraz-core</code> package in the web
39 interface directory (<code>/docuserver/www</code>). This will create 40 interface directory (<code>/docuserver/www</code>). This will create
40 the digilib directory <code>digitallibrary</code>.</li> 41 the digilib directory <code>digitallibrary</code>.</li>
41 <li>(optional) Unpack the <code>digilib-ext</code> package in the 42
42 docuserver directory.</li> 43 <li>Unpack Jakarta Tomcat 4.1.24 in <code>/docuserver</code> This should
43 <li>Unpack Jakarta tomcat 4.0.1 in <code>/opt</code> This should 44 produce a directory <code>/docuserver/jakarta-tomcat-4.1.24</code>. Create a
44 produce a directory <code>/opt/jakarta-tomcat-4.0.1</code>. Create a 45 link <code>/docuserver/tomcat</code> to the new directory.</li>
45 link <code>/opt/tomcat</code> to the new directory.</li> 46
46 <li>Unpack the configuration files package 47 <li>(optional) Unpack the configuration files package
47 <code>digilib-tomconf</code> in the tomcat directory.</li> 48 <code>digilib-tomconf</code> in the tomcat directory.</li>
48 <li>Adjust hostname and HTML-base directory in the file 49
49 <code>server.xml</code> (in the directory 50 <li>Create a link from the digilib directory into the Tomcat webapps
50 <code>/opt/tomcat/conf</code>, see below for details))</li> 51 directory <code>/docuserver/tomcat/webapps</code> (type <code>ln -s
52 /docuserver/www/digitallibrary /docuserver/tomcat/webapps</code>) This is
53 the default installation running on port 8080 as
54 <code>http://myserver:8080/digitallibrary/</code>.</li>
55
51 <li>Adjust the path to the JDK and its options in 56 <li>Adjust the path to the JDK and its options in
52 <code>catalina.sh</code> (in the directory 57 <code>catalina.sh</code> (in the directory
53 <code>/opt/tomcat/bin</code>, see below for details)</li> 58 <code>/docuserver/tomcat/bin</code>, see below for details)</li>
59
54 <li>(optional) For SuSE Linux you can use the startup skript 60 <li>(optional) For SuSE Linux you can use the startup skript
55 <code>tomcat/bin/rctomcat</code> 61 <code>tomcat/bin/rctomcat</code>
56 to start and stop the tomcat server. Copy the script into 62 to start and stop the tomcat server. Copy the script into
57 <code>/etc/init.d</code> as <code>tomcat</code> and set runlevel 63 <code>/etc/init.d</code> as <code>tomcat</code> and set runlevel
58 links accordingly.</li> 64 links accordingly.</li>
65
59 <li>(optional) Set the tomcat directory and all files to be owned by 66 <li>(optional) Set the tomcat directory and all files to be owned by
60 the user 67 the user <code>wwwrun</code> (or whatever your webserver runs) and
61 <code>wwwrun</code> (or whatever your webserver runs) and use this 68 use this account to start the tomcat server.</li>
62 account to start the tomcat server.</li> 69
70 <li>to use Mozilla-XUL functionality a user have to open the page
71 http://myserver:8080/digitallibrary/xul/install_sidebar.jsp
72 in a mozilla compatible browser and press the button 'install button
73 list into sidebar'</li>
74
63 </ol> 75 </ol>
64 76
65 77
66 <!-- 78 <!--
67 <h2>Apache connector module</h2> 79 <h2>Apache connector module</h2>
80 92
81 <h2>Tomcat</h2> 93 <h2>Tomcat</h2>
82 94
83 <h3>catalina.sh</h3> 95 <h3>catalina.sh</h3>
84 96
85 <p>The file <code>catalina.sh</code> (in <code>/opt/tomcat/bin</code> 97 <p>The file <code>catalina.sh</code> (in <code>/docuserver/tomcat/bin</code>
86 has been modified to provide the path to the JDK and runtime options 98 can be 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 99 for the Java VM. Somewhere at the beginning of the file you can put two lines
88 like this:</p> 100 like this:</p>
89 101
90 <pre> 102 <pre>
91 export JAVA_HOME=/usr/local/lib/IBMJava2-13 103 export JAVA_HOME=/usr/local/lib/IBMJava2-13
92 export CATALINA_OPTS="-mx512m" 104 export CATALINA_OPTS="-mx512m"
96 installation directory. You can adjust the memory used by the Java VM 108 installation directory. You can adjust the memory used by the Java VM
97 with the <code>-mx512m</code> option.</p> 109 with the <code>-mx512m</code> option.</p>
98 110
99 <p>You can delete those two lines if you set these variables in your 111 <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 112 shell before starting tomcat in that same shell. These lines are
101 needed if you want to use the startup script for linux mentioned 113 needed if you want to use the startup script mentioned above under
102 above.</p> 114 linux .</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 115
172 116
173 <h3>tomcat-users.xml</h3> 117 <h3>tomcat-users.xml</h3>
174 118
175 <p>All passwords and usernames have to be set up in the file 119 <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 120 <code>tomcat-users.xml</code> in <code>/docuserver/tomcat/conf</code> if you
177 want to use authentication in digilib. The file looks like this:</p> 121 want to use authentication in digilib. The file looks like this:</p>
178 122
179 <pre> 123 <pre>
180 &lt;tomcat-users&gt; 124 &lt;tomcat-users&gt;
181 &lt;user name="tomcat" password="tomcat" roles="tomcat" /&gt; 125 &lt;user name="tomcat" password="tomcat" roles="tomcat" /&gt;
190 restricted resource. A user can have one or more 134 restricted resource. A user can have one or more
191 <code>roles</code>. These roles will be used by digilib to decide if 135 <code>roles</code>. These roles will be used by digilib to decide if
192 an authenticated user is allowed to access a document (see 136 an authenticated user is allowed to access a document (see
193 <code>digilib-auth.xml</code> below).</p> 137 <code>digilib-auth.xml</code> below).</p>
194 138
139 <p>If you want to use the webinterface to configure Tomcat, you have to
140 add administrational account with the roles <code>admin</code> and
141 <code>manager</code>.</p>
142
195 <p>tomcat has to be restarted before changes to 143 <p>tomcat has to be restarted before changes to
196 <code>tomcat-users.xml</code> have effect!</p> 144 <code>tomcat-users.xml</code> have effect!</p>
145
197 146
198 <h2>Digilib</h2> 147 <h2>Digilib</h2>
199 148
200 <h3>web.xml</h3> 149 <h3>web.xml</h3>
201 150
202 <p>The deployment of the digilib servlets and JSPs is defined in the 151 <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 152 file <code>web.xml</code> in the <code>WEB-INF</code> subdirectory of
204 the digilib directory 153 the digilib directory
205 (<code>/docuserver/www/digitallibrary/WEB-INF</code>).</p> 154 (<code>/docuserver/www/digitallibrary/WEB-INF</code>).</p>
206 155
207 <p>The only parameter you might have to adjust is the position of the 156 <p>The only parameter you will have to adjust is the position of the
208 digilib configuration file. The parameter occurs twice in the file and 157 digilib configuration file. The parameter occurs twice in the file and
209 looks like this:</p> 158 looks like this:</p>
210 159
211 <pre> 160 <pre>
212 &lt;!-- parameters to the servlet --&gt; 161 &lt;!-- parameters to the servlet --&gt;
216 <b>/docuserver/www/digitallibrary/WEB-INF/digilib-config.xml</b> 165 <b>/docuserver/www/digitallibrary/WEB-INF/digilib-config.xml</b>
217 &lt;/param-value&gt; 166 &lt;/param-value&gt;
218 &lt;/init-param&gt; 167 &lt;/init-param&gt;
219 </pre> 168 </pre>
220 169
221 <p>Change the path to where you installed the configuration files.</p> 170 <p>Change the path to point where you installed the configuration files.</p>
222 171
223 <p>Make shure to change the parameter in both places! It is needed 172 <p>Make shure to change the parameter in both places in the config
224 both for the servlet and the JSP pages!</p> 173 file! It is needed both for the servlet and the JSP pages!</p>
174
225 175
226 <h3>digilib-config.xml</h3> 176 <h3>digilib-config.xml</h3>
227 177
228 <p>The main configuration for digilib is 178 <p>The main configuration for digilib is
229 <code>digilib-config.xml</code>. It's position is defined by the 179 <code>digilib-config.xml</code>. It's position is defined by the
244 194
245 &lt;!-- Image to be sent to indicate authorization failure. --&gt; 195 &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; 196 &lt;parameter name="denied-image" value=<b>"/docuserver/images/icons/alert.red.gif"</b> /&gt;
247 197
248 &lt;!-- List of directories where images are searched. 198 &lt;!-- List of directories where images are searched.
249 Directories with low-resolution images are first in list. --&gt; 199 The authoritative directory with the high-resolution images
250 &lt;parameter name="basedir-list" value=<b>"/docuserver/scaled/small:/docuserver/images:/docuserver/scans/quellen"</b> /&gt; 200 is first in list. --&gt;
201 &lt;parameter name="basedir-list" value=<b>"/docuserver/images:/docuserver/scaled/small"</b> /&gt;
251 202
252 &lt;!-- Restrict access to authorized users. 203 &lt;!-- Restrict access to authorized users.
253 User authentication and roles are provided by the servlet container 204 User authentication and roles are provided by the servlet container
254 (see tomcat-users.xml). 205 (see tomcat-users.xml).
255 Authorization for resources (directories) is evaluated by the servlet 206 Authorization for resources (directories) is evaluated by the servlet
256 (see auth-file). --&gt; 207 (see auth-file). --&gt;
257 &lt;parameter name="use-authorization" value="true" /&gt; 208 &lt;parameter name="use-authorization" value="true" /&gt;
258 209
259 &lt;!-- URL location of XML file with authorization requirements. --&gt; 210 &lt;!-- 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; 211 &lt;parameter name="auth-file" value=<b>"/docuserver/www/digitallibrary/WEB-INF/digilib-auth.xml"</b> /&gt;
261 212
262 &lt;!-- Part of URL to indicate authenticated access to Tomcat. --&gt; 213 &lt;!-- Part of URL to indicate authenticated access to Tomcat. --&gt;
263 &lt;parameter name="auth-url-path" value="authenticated/" /&gt; 214 &lt;parameter name="auth-url-path" value="authenticated/" /&gt;
264 &lt;/digilib-config&gt; 215 &lt;/digilib-config&gt;
265 </pre> 216 </pre>
266 217
267 <p>You have to adjust the <code>basedir-list</code> parameter to the 218 <p>You have to adjust the <code>basedir-list</code> parameter to the
268 directories where your images are installed. You need only one 219 directories where your images are installed. You need only one
269 directory if you do not have prescaled low resolution versions of your 220 directory if you do not have prescaled low resolution versions of your
270 images.</p> 221 images. The directory with the high-resolution versions must be the
222 first entry in the list.</p>
271 223
272 <p>You can supply your own images for the &quot;error&quot; and 224 <p>You can supply your own images for the &quot;error&quot; and
273 &quot;access denied&quot; messages by the servlet. Standard images 225 &quot;access denied&quot; messages by the servlet. Standard images
274 will be used if these parameters are undefined.</p> 226 will be used if these parameters are undefined.</p>
275 227
330 282
331 283
332 284
333 <hr> 285 <hr>
334 <address>robert.casties@philo.unibe.ch</address> 286 <address>robert.casties@philo.unibe.ch</address>
335 <!-- hhmts start --> Last modified: Thu Jan 17 19:12:01 CET 2002 <!-- hhmts end --> 287 <!-- hhmts start -->Last modified: Tue May 13 23:35:13 CEST 2003 <!-- hhmts end -->
336 </body> </html> 288 </body> </html>