Mercurial > hg > digilib
comparison digilib-config.html @ 1659:fe8300fdcd9d
Creating site for 2.5-SNAPSHOT
author | Robert Casties <casties@mpiwg-berlin.mpg.de> |
---|---|
date | Mon, 20 Nov 2017 20:24:00 +0000 |
parents | 636e7342b1b6 |
children | 1beeb9319d78 |
comparison
equal
deleted
inserted
replaced
1642:636e7342b1b6 | 1659:fe8300fdcd9d |
---|---|
1 <!DOCTYPE html> | 1 <!DOCTYPE html> |
2 <!-- | 2 <!-- |
3 | Generated by Apache Maven Doxia at 2017-08-22 | 3 | Generated by Apache Maven Doxia at 2017-11-20 |
4 | Rendered using Apache Maven Fluido Skin 1.3.0 | 4 | Rendered using Apache Maven Fluido Skin 1.3.0 |
5 --> | 5 --> |
6 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> | 6 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> |
7 <head> | 7 <head> |
8 <meta charset="UTF-8" /> | 8 <meta charset="UTF-8" /> |
9 <meta name="viewport" content="width=device-width, initial-scale=1.0" /> | 9 <meta name="viewport" content="width=device-width, initial-scale=1.0" /> |
10 <meta name="Date-Revision-yyyymmdd" content="20170822" /> | 10 <meta name="Date-Revision-yyyymmdd" content="20171120" /> |
11 <meta http-equiv="Content-Language" content="en" /> | 11 <meta http-equiv="Content-Language" content="en" /> |
12 <title>digilib - The Digital Image Library – Configuring digilib</title> | 12 <title>digilib - The Digital Image Library – Configuring digilib</title> |
13 <link rel="stylesheet" href="./css/apache-maven-fluido-1.3.0.min.css" /> | 13 <link rel="stylesheet" href="./css/apache-maven-fluido-1.3.0.min.css" /> |
14 <link rel="stylesheet" href="./css/site.css" /> | 14 <link rel="stylesheet" href="./css/site.css" /> |
15 <link rel="stylesheet" href="./css/print.css" media="print" /> | 15 <link rel="stylesheet" href="./css/print.css" media="print" /> |
39 | 39 |
40 <div id="breadcrumbs"> | 40 <div id="breadcrumbs"> |
41 <ul class="breadcrumb"> | 41 <ul class="breadcrumb"> |
42 | 42 |
43 | 43 |
44 <li id="publishDate">Last Published: 2017-08-22</li> | 44 <li id="publishDate">Last Published: 2017-11-20</li> |
45 <li class="divider">|</li> <li id="projectVersion">Version: 2.5-SNAPSHOT</li> | 45 <li class="divider">|</li> <li id="projectVersion">Version: 2.5-SNAPSHOT</li> |
46 | 46 |
47 | 47 |
48 | 48 |
49 | 49 |
88 </li> | 88 </li> |
89 <li class="nav-header">Installation</li> | 89 <li class="nav-header">Installation</li> |
90 | 90 |
91 <li> | 91 <li> |
92 | 92 |
93 <a href="build-maven.html" title="Building digilib"> | |
94 <i class="none"></i> | |
95 Building digilib</a> | |
96 </li> | |
97 | |
98 <li> | |
99 | |
93 <a href="install-digilib.html" title="Installing digilib"> | 100 <a href="install-digilib.html" title="Installing digilib"> |
94 <i class="none"></i> | 101 <i class="none"></i> |
95 Installing digilib</a> | 102 Installing digilib</a> |
96 </li> | 103 </li> |
97 | 104 |
98 <li> | 105 <li> |
99 | 106 |
100 <a href="build-maven.html" title="Building digilib"> | 107 <a href="server-setups.html" title="Server setups"> |
101 <i class="none"></i> | 108 <i class="none"></i> |
102 Building digilib</a> | 109 Server setups</a> |
103 </li> | 110 </li> |
104 <li class="nav-header">Configuration</li> | 111 <li class="nav-header">Configuration</li> |
105 | 112 |
106 <li class="active"> | 113 <li class="active"> |
107 | 114 |
176 <div class="clear"></div> | 183 <div class="clear"></div> |
177 <div class="clear"></div> | 184 <div class="clear"></div> |
178 <a href="http://maven.apache.org/" title="Built by Maven" class="builtBy"> | 185 <a href="http://maven.apache.org/" title="Built by Maven" class="builtBy"> |
179 <img class="builtBy" alt="Built by Maven" src="https://maven.apache.org/images/logos/maven-feather.png" /> | 186 <img class="builtBy" alt="Built by Maven" src="https://maven.apache.org/images/logos/maven-feather.png" /> |
180 </a> | 187 </a> |
181 <a href="https://github.com/" title="Hosted by GitHub" class="builtBy"> | 188 <a href="../../" title="Hosted by GitHub" class="builtBy"> |
182 <img class="builtBy" alt="Hosted by GitHub" src="https://assets-cdn.github.com/images/modules/logos_page/GitHub-Logo.png" width="200px" /> | 189 <img class="builtBy" alt="Hosted by GitHub" src="https://assets-cdn.github.com/images/modules/logos_page/GitHub-Logo.png" width="200px" /> |
183 </a> | 190 </a> |
184 <a href="http://www.sourceforge.net/" title="Hosted by SourceForge" class="builtBy"> | 191 <a href="http://www.sourceforge.net/" title="Hosted by SourceForge" class="builtBy"> |
185 <img class="builtBy" alt="Hosted by SourceForge" src="https://upload.wikimedia.org/wikipedia/commons/0/0b/Sourceforge_logo.png" /> | 192 <img class="builtBy" alt="Hosted by SourceForge" src="https://upload.wikimedia.org/wikipedia/commons/0/0b/Sourceforge_logo.png" /> |
186 </a> | 193 </a> |
190 | 197 |
191 | 198 |
192 <div id="bodyColumn" class="span9" > | 199 <div id="bodyColumn" class="span9" > |
193 | 200 |
194 <h1>Configuring digilib</h1> | 201 <h1>Configuring digilib</h1> |
195 <div class="section"> | 202 <p>The main configuration for <i>digilib</i> is the XML file <tt>digilib-config.xml</tt> in the <tt>WEB-INF</tt> directory of the webapp. Alternatively you can also use a Java properties file <tt>digilib.properties</tt> somewhere in the classpath. (If you really need a different location for the XML file you can define it in the <tt>config-file</tt> init-parameter to the Servlet. <b>TODO</b> add an example)</p> |
196 <h2><a name="digilib-config.xml"></a>digilib-config.xml</h2> | 203 <p>In the configuration file you can set lots of paths and options. <i>digilib</i> uses default values for all configuration settings that meet most requirements. Hence you have to configure only the settings that you want to change. The <b><tt>basedir-list</tt></b> parameter however is <b>mandatory</b> unless you only want to serve the contributed example images for an evaluation.</p> |
197 <p>The main configuration for digilib is the XML file <tt>digilib-config.xml</tt> in the <tt>WEB-INF</tt> directory in the webapp or a Java properties file <tt>digilib.properties</tt> somewhere in the classpath. (If you really need a different location for the XML file you can define it in the <tt>config-file</tt> init-parameter to the Servlet.)</p> | 204 <p>All options are defined as <tt>parameter</tt> elements with the attributes <tt>name</tt> and <tt>value</tt> that are wrapped in the root element <tt>digilib-config</tt>. A minimal configuration looks like this:</p> |
198 <p>In the configuration file you can set lots of paths and options. digilib uses default values for all configuration settings that meet most requirements so you have to configure only the settings that you want to change.</p> | 205 |
199 <p>You have to adjust the <b><tt>basedir-list</tt></b> parameter to the directories where your images are installed. The directory path has to be an absolute path following the conventions of your operating system (a relative path is taken to be relative to the web application directory).</p> | 206 <div class="source"> |
200 <p>You need only one directory if you don’t want to provide pre-scaled low resolution versions of your images. If you have pre-scaled images the directory with the high-resolution images must be the first entry in the list.</p> | 207 <div class="source"> |
201 <p>Documentation on the directory layout and on using pre-scaled images is <a href="image-directories.html">here</a>.</p> | 208 <pre><?xml version="1.0" encoding="UTF-8"?> |
202 <p>A minimal configuration looks like this:</p> | |
203 | |
204 <div class="source"> | |
205 <div class="source"> | |
206 <pre><!-- Digilib servlet config file --> | |
207 <digilib-config> | 209 <digilib-config> |
208 <!-- List of directories where images are searched. | 210 <parameter name="basedir-list" value="/usr/local/images" /> |
209 The authoritative directory with the high-resolution images | |
210 is first in list. --> | |
211 <parameter name="basedir-list" value="/docuserver/images" /> | |
212 </digilib-config> | 211 </digilib-config> |
213 </pre></div></div> | 212 </pre></div></div> |
214 <p>A more customized configuration may look like the following (for another commented example see <a class="externalLink" href="https://sourceforge.net/p/digilib/code/ci/default/tree/webapp/src/main/webapp/WEB-INF/digilib-config.xml.template">digilib-config.xml.template</a>, for a full list of configuration options and their default values use the source: <a class="externalLink" href="https://sourceforge.net/p/digilib/code/ci/default/tree/common/src/main/java/digilib/conf/DigilibConfiguration.java">DigilibConfiguration</a>, <a class="externalLink" href="https://sourceforge.net/p/digilib/code/ci/default/tree/servlet/src/main/java/digilib/conf/DigilibServletConfiguration.java">DigilibServletConfiguration</a>, <a class="externalLink" href="https://sourceforge.net/p/digilib/code/ci/default/tree/servlet3/src/main/java/digilib/conf/DigilibServlet3Configuration.java">DigilibServlet3Configuration</a> ):</p> | 213 <p>A more extensive example is included in the sources as <a class="externalLink" href="https://github.com/robcast/digilib/blob/master/webapp/src/main/webapp/WEB-INF/digilib-config.xml.template">digilib-config.xml.template</a>.</p> |
215 | 214 <div class="section"> |
216 <div class="source"> | 215 <h2><a name="Available_parameters"></a>Available parameters</h2> |
217 <div class="source"> | 216 <p>The documented parameter values below are the defaults.</p> |
218 <pre><!-- Digilib servlet config file --> | 217 <p>If relative paths are provided as file locations, these will be resolved with the web application’s directory as base.</p> |
219 <digilib-config> | 218 <p>You can inspect a summary of your running digilib configuration at the URL <tt><base_url>/server/dlConfig.jsp</tt>.</p> |
220 <!-- Image to be sent to indicate general failure. --> | 219 <div class="section"> |
221 <parameter name="error-image" value="/docuserver/images/icons/broken.gif" /> | 220 <h3><a name="Image_locations"></a>Image locations</h3> |
222 | 221 |
223 <!-- Image to be sent to indicate authorization failure. --> | 222 <div class="source"> |
224 <parameter name="denied-image" value="/docuserver/images/icons/alert.red.gif" /> | 223 <div class="source"> |
225 | 224 <pre><parameter name="basedir-list" value="sample-images" /> |
226 <!-- Image to be sent to indicate file-not-found. --> | 225 </pre></div></div> |
227 <parameter name="notfound-image" value="/docuserver/images/icons/notfound.gif" /> | 226 <p>A list of directories where images are searched. See <a href="image-directories.html">this document</a> for details.</p> |
228 | 227 |
229 <!-- List of directories where images are searched. | 228 <div class="source"> |
230 The authoritative directory with the high-resolution images | 229 <div class="source"> |
231 is first in list. --> | 230 <pre><parameter name="denied-image" value="img/digilib-denied.png" /> |
232 <parameter name="basedir-list" value="/docuserver/images:/docuserver/scaled/small" /> | 231 </pre></div></div> |
233 | 232 <p>This image is sent to indicate an authorization failure.</p> |
234 <!-- default interpolation quality (0=worst) --> | 233 |
235 <parameter name="default-quality" value="2"/> | 234 <div class="source"> |
236 | 235 <div class="source"> |
237 <!-- is sending whole image files with mo=file allowed? --> | 236 <pre><parameter name="error-image" value="img/digilib-error.png" /> |
238 <parameter name="sendfile-allowed" value="true" /> | 237 </pre></div></div> |
239 | 238 <p>This image is sent to indicate a general failure.</p> |
240 <!-- the a maximum size of any sent image. (0 means no limit) --> | 239 |
241 <parameter name="max-image-size" value="0" /> | 240 <div class="source"> |
242 | 241 <div class="source"> |
243 <!-- number of working threads --> | 242 <pre><parameter name="notfound-image" value="img/digilib-notfound.png" /> |
244 <parameter name="worker-threads" value="2" /> | 243 </pre></div></div> |
245 | 244 <p>This image to sent to indicate that the requested image does not exist or could not be read.</p> |
246 <!-- number of waiting requests in queue --> | 245 |
247 <parameter name="max-waiting-threads" value="20" /> | 246 <div class="source"> |
248 | 247 <div class="source"> |
249 <!-- Restrict access to authorized users --> | 248 <pre><parameter name="use-mapping" value="false" /> |
250 <parameter name="use-authorization" value="false"/> | 249 </pre></div></div> |
251 | 250 <p>Enables the mapping of ‘virtual directories’ to actual directories in the filesystem using a mapping file.</p> |
252 <!-- use mapping of "virtual directories" to real directories on the server --> | 251 |
253 <parameter name="use-mapping" value="true"/> | 252 <div class="source"> |
254 | 253 <div class="source"> |
255 <!-- location of XML name mapping file --> | 254 <pre><parameter name="mapping-file" value="digilib-map.xml" /> |
256 <parameter name="mapping-file" value="digilib-map.xml"/> | 255 </pre></div></div> |
257 | 256 <p>The location of the mapping file. Refer to <a class="externalLink" href="https://github.com/robcast/digilib/blob/master/webapp/src/main/webapp/WEB-INF/digilib-map.xml.template">digilib-map.xml.template</a> for an example. </p> |
258 <!-- location of logger config file --> | 257 <p>The file contains <tt>mapping</tt> elements with a <tt>link</tt> attribute containing a ‘virtual directory’ name that is mapped to the directory given in the <tt>dir</tt> attribute.</p></div> |
259 <parameter name="log-config-file" value="log4j-config.xml"/> | 258 <div class="section"> |
260 </digilib-config> | 259 <h3><a name="Image_processing_options"></a>Image processing options</h3> |
261 </pre></div></div> | 260 |
262 <p>You can supply your own icons for the “error” and “access denied” messages by the servlet. Standard images will be used if these parameters are not defined.</p> | 261 <div class="source"> |
263 <p>If you need authorization set <tt>use-authorization</tt> to true and read the <a href="auth.html">documentation on authentication and authorization</a>.</p> | 262 <div class="source"> |
264 <p>You can see a summary of your running digilib configuration at the URL <a class="externalLink" href="http://localhost:8080/digitallibrary/server/dlConfig.jsp">http://localhost:8080/digitallibrary/server/dlConfig.jsp</a></p></div> | 263 <pre><parameter name="default-quality" value="2" /> |
264 </pre></div></div> | |
265 <p>The default interpolation quality.</p> | |
266 | |
267 <ul> | |
268 | |
269 <li><tt>0</tt>: do not use interpolation (worst),</li> | |
270 | |
271 <li><tt>1</tt>: use linear interpolation,</li> | |
272 | |
273 <li><tt>2</tt>: use bilinear interpolation and blur-before-scale (best).</li> | |
274 </ul> | |
275 | |
276 <div class="source"> | |
277 <div class="source"> | |
278 <pre><parameter name="max-image-size" value="0" /> | |
279 </pre></div></div> | |
280 <p>The maximum size of delivered images as pixel area, <tt>40000</tt> means up to 200x200 or 100x400, <tt>0</tt> means no limit.</p> | |
281 | |
282 <div class="source"> | |
283 <div class="source"> | |
284 <pre><parameter name="sendfile-allowed" value="true" /> | |
285 </pre></div></div> | |
286 <p>Defines whether requests with <tt>mo=file</tt> or <tt>mo=rawfile</tt> as parameter are allowed to download files (see <a href="scaler-api.html">Scaler API</a>).</p> | |
287 | |
288 <div class="source"> | |
289 <div class="source"> | |
290 <pre><parameter name="subsample-minimum" value="2.0" /> | |
291 </pre></div></div> | |
292 <p>Degree of subsampling on image load. This is the minimum factor that is scaled by interpolation and not by subsampling, i.e. by skipping pixels.</p></div> | |
293 <div class="section"> | |
294 <h3><a name="Authentication_and_authorization"></a>Authentication and authorization</h3> | |
295 <p>Details are provided in the <a href="auth.html">documentation on authentication and authorization</a>.</p> | |
296 | |
297 <div class="source"> | |
298 <div class="source"> | |
299 <pre><parameter name="auth-file" value="digilib-auth.xml" /> | |
300 </pre></div></div> | |
301 <p>Configuration file for authentication and authorization. The format and content of the configuration file is determined by the chosen authentication and authorization classes. </p> | |
302 | |
303 <div class="source"> | |
304 <div class="source"> | |
305 <pre><parameter name="authn-token-cookie" value="id_token" /> | |
306 </pre></div></div> | |
307 <p>The name of the cookie that holds the authentication token for <tt>digilib.auth.OpenIdAuthnOps</tt>.</p> | |
308 | |
309 <div class="source"> | |
310 <div class="source"> | |
311 <pre><parameter name="authnops-class" value="digilib.auth.IpAuthnOps" /> | |
312 </pre></div></div> | |
313 <p>The class to handle authentication.</p> | |
314 | |
315 <div class="source"> | |
316 <div class="source"> | |
317 <pre><parameter name="authzops-class" value="digilib.auth.PathAuthzOps" /> | |
318 </pre></div></div> | |
319 <p>The class to handle authorization.</p> | |
320 | |
321 <div class="source"> | |
322 <div class="source"> | |
323 <pre><parameter name="use-authorization" value="false" /> | |
324 </pre></div></div> | |
325 <p>Enable or disable all authorization. If <tt>use-authorization</tt> is <tt>true</tt> it also needs to be configured using <tt>authnops-class</tt> and <tt>authzops-class</tt> and the <tt>auth-file</tt>.</p></div> | |
326 <div class="section"> | |
327 <h3><a name="IIIF_API_options"></a>IIIF API options</h3> | |
328 <p>The options configure the IIIF interface. For more information see the <a href="iiif-api">digilib IIIF documentation</a></p> | |
329 | |
330 <div class="source"> | |
331 <div class="source"> | |
332 <pre><parameter name="iiif-api-version" value="2.1" /> | |
333 </pre></div></div> | |
334 <p>The IIIF API version for the generated <tt>info.json</tt> information response. </p> | |
335 | |
336 <div class="source"> | |
337 <div class="source"> | |
338 <pre><parameter name="iiif-info-cors" value="true" /> | |
339 </pre></div></div> | |
340 <p>Enables the <tt>Cross-Origin Resource Sharing</tt> header in IIIF info requests.</p> | |
341 | |
342 <div class="source"> | |
343 <div class="source"> | |
344 <pre><parameter name="iiif-image-cors" value="true" /> | |
345 </pre></div></div> | |
346 <p>Enables the <tt>Cross-Origin Resource Sharing</tt> header in IIIF image requests.</p> | |
347 | |
348 <div class="source"> | |
349 <div class="source"> | |
350 <pre><parameter name="iiif-prefix" value="IIIF" /> | |
351 </pre></div></div> | |
352 <p>The prefix (after <tt>Scaler</tt>) that leads to the IIIF API.</p> | |
353 | |
354 <div class="source"> | |
355 <div class="source"> | |
356 <pre><parameter name="iiif-slash-replacement" value="!" /> | |
357 </pre></div></div> | |
358 <p>The character that replaces a slash in the identifier of IIIF requests.</p></div> | |
359 <div class="section"> | |
360 <h3><a name="Threading_options"></a>Threading options</h3> | |
361 | |
362 <div class="source"> | |
363 <div class="source"> | |
364 <pre><parameter name="max-waiting-threads" value="20" /> | |
365 </pre></div></div> | |
366 <p>The maximum number of requests waiting in the queue before sending “service unavailable”.</p> | |
367 | |
368 <div class="source"> | |
369 <div class="source"> | |
370 <pre><parameter name="worker-threads" value="2" /> | |
371 </pre></div></div> | |
372 <p>The maximum number of concurrently working threads.</p> | |
373 | |
374 <div class="source"> | |
375 <div class="source"> | |
376 <pre><parameter name="worker-timeout" value="60000" /> | |
377 </pre></div></div> | |
378 <p>Timeout for worker threads in milliseconds.</p></div> | |
379 <div class="section"> | |
380 <h3><a name="Assorted_options"></a>Assorted options</h3> | |
381 | |
382 <div class="source"> | |
383 <div class="source"> | |
384 <pre><parameter name="default-errmsg-type" value="image" /> | |
385 </pre></div></div> | |
386 <p>Defines how errors are presented to the user. Allowed values are <tt>code</tt>, <tt>image</tt> and <tt>text</tt>.</p> | |
387 | |
388 <ul> | |
389 | |
390 <li><tt>image</tt> sends an error-image as error code (see <tt>denied-image</tt>, <tt>error-image</tt>, <tt>notfound-image</tt> parameters).</li> | |
391 | |
392 <li><tt>code</tt> sends an HTTP error code, which may result in a broken image display in the browser.</li> | |
393 | |
394 <li><tt>text</tt> sends a plain-text error message, which may result in a broken image display in the browser.</li> | |
395 </ul> | |
396 | |
397 <div class="source"> | |
398 <div class="source"> | |
399 <pre><parameter name="img-diskcache-allowed" value="false" /> | |
400 </pre></div></div> | |
401 <p>Enables the use of a disk cache for the image toolkit. Using the disk cache may leak file handles and lead to resource issues if digilib runs for a long time.</p> | |
402 | |
403 <div class="source"> | |
404 <div class="source"> | |
405 <pre><parameter name="log-config-file" value="log4j-config.xml" /> | |
406 </pre></div></div> | |
407 <p>Location of the logging configuration file. The current logger is <a class="externalLink" href="https://logging.apache.org/log4j/1.2/manual.html">Log4J 1.2</a>.</p></div> | |
408 <div class="section"> | |
409 <h3><a name="Unknown_category"></a>Unknown category</h3> | |
410 <p><b>TODO</b> move items to appropriate sections</p> | |
411 | |
412 <div class="source"> | |
413 <div class="source"> | |
414 <pre><parameter name="dirmeta-class" value="digilib.meta.IndexMetaDirMeta" /> | |
415 </pre></div></div> | |
416 <p>Class for <b>TODO</b>.</p> | |
417 | |
418 <div class="source"> | |
419 <div class="source"> | |
420 <pre><parameter name="docudirectory-class" value="digilib.io.BaseDirDocuDirectory" /> | |
421 </pre></div></div> | |
422 <p>Class for <b>TODO</b>.</p> | |
423 | |
424 <div class="source"> | |
425 <div class="source"> | |
426 <pre><parameter name="docuimage-class" value="digilib.image.ImageLoaderDocuImage" /> | |
427 </pre></div></div> | |
428 <p>Class for the <tt>DocuImage</tt> instance, <b>TODO</b> elaborate intended use</p> | |
429 | |
430 <div class="source"> | |
431 <div class="source"> | |
432 <pre><parameter name="docuimage-hacks" value="" /> | |
433 </pre></div></div> | |
434 <p><b>TODO</b> elaborate</p> | |
435 | |
436 <div class="source"> | |
437 <div class="source"> | |
438 <pre><parameter name="filemeta-class" value="digilib.meta.IndexMetaFileMeta" /> | |
439 </pre></div></div> | |
440 <p>Class for <b>TODO</b>.</p></div></div> | |
265 </div> | 441 </div> |
266 </div> | 442 </div> |
267 </div> | 443 </div> |
268 | 444 |
269 <hr/> | 445 <hr/> |
270 | 446 |
271 <footer> | 447 <footer> |
272 <div class="container-fluid"> | 448 <div class="container-fluid"> |
273 <div class="row span12">Copyright © 2001-2017 | 449 <div class="row span12">Copyright © 2001-2017 |
274 <a href="https://github.com/robcast/digilib">digilib Community</a>. | 450 <a href="https://robcast.github.io/digilib/">digilib Community</a>. |
275 All Rights Reserved. | 451 All Rights Reserved. |
276 | 452 |
277 </div> | 453 </div> |
278 | 454 |
279 | 455 |