Mercurial > hg > digilib

view digilib-config.html @ 1666:1beeb9319d78

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Creating site for 2.5-SNAPSHOT
author Robert Casties <casties@mpiwg-berlin.mpg.de>
date Tue, 21 Nov 2017 19:34:58 +0000
parents fe8300fdcd9d
children 8a9c66abb57c
line wrap: on
line source

<!DOCTYPE html>
<!--
 | Generated by Apache Maven Doxia at 2017-11-21
 | Rendered using Apache Maven Fluido Skin 1.3.0
-->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta name="Date-Revision-yyyymmdd" content="20171121" />
    <meta http-equiv="Content-Language" content="en" />
    <title>digilib - The Digital Image Library &#x2013; Configuring digilib</title>
    <link rel="stylesheet" href="./css/apache-maven-fluido-1.3.0.min.css" />
    <link rel="stylesheet" href="./css/site.css" />
    <link rel="stylesheet" href="./css/print.css" media="print" />

      
    <script type="text/javascript" src="./js/apache-maven-fluido-1.3.0.min.js"></script>

    
            </head>
        <body class="topBarDisabled">
          
        
    
        <div class="container-fluid">
          <div id="banner">
        <div class="pull-left">
                                    <a href="https://robcast.github.io/digilib/" id="bannerLeft">
                <h2>digilib - a versatile image viewing environment for the internet</h2>
                </a>
                      </div>
        <div class="pull-right">                  <a href="https://robcast.github.io/digilib/" id="bannerRight">
                                                                                                <img src="images/digilib-logo-small.png" />
                </a>
      </div>
        <div class="clear"><hr/></div>
      </div>

      <div id="breadcrumbs">
        <ul class="breadcrumb">
                
                    
                  <li id="publishDate">Last Published: 2017-11-21</li>
                  <li class="divider">|</li> <li id="projectVersion">Version: 2.5-SNAPSHOT</li>
                      
                
                    
      
                            </ul>
      </div>

            
      <div class="row-fluid">
        <div id="leftColumn" class="span3">
          <div class="well sidebar-nav">
                
                    
                <ul class="nav nav-list">
                    <li class="nav-header">Overview</li>
                                
      <li>
    
                          <a href="index.html" title="About digilib">
          <i class="none"></i>
        About digilib</a>
            </li>
                  
      <li>
    
                          <a href="features.html" title="digilib features">
          <i class="none"></i>
        digilib features</a>
            </li>
                  
      <li>
    
                          <a href="digilib-short.html" title="How digilib works">
          <i class="none"></i>
        How digilib works</a>
            </li>
                  
      <li>
    
                          <a href="history.html" title="Ancient history">
          <i class="none"></i>
        Ancient history</a>
            </li>
                              <li class="nav-header">Installation</li>
                                
      <li>
    
                          <a href="build-maven.html" title="Building digilib">
          <i class="none"></i>
        Building digilib</a>
            </li>
                  
      <li>
    
                          <a href="install-digilib.html" title="Installing digilib">
          <i class="none"></i>
        Installing digilib</a>
            </li>
                  
      <li>
    
                          <a href="server-setups.html" title="Server setups">
          <i class="none"></i>
        Server setups</a>
            </li>
                              <li class="nav-header">Configuration</li>
                                
      <li class="active">
    
            <a href="#"><i class="none"></i>Configuring digilib</a>
          </li>
                  
      <li>
    
                          <a href="image-directories.html" title="Directory layout">
          <i class="none"></i>
        Directory layout</a>
            </li>
                  
      <li>
    
                          <a href="java-settings.html" title="Java settings and tuning">
          <i class="none"></i>
        Java settings and tuning</a>
            </li>
                  
      <li>
    
                          <a href="auth.html" title="Access control">
          <i class="none"></i>
        Access control</a>
            </li>
                              <li class="nav-header">Development</li>
                                
      <li>
    
                          <a href="scaler-api.html" title="The digilib Scaler API">
          <i class="none"></i>
        The digilib Scaler API</a>
            </li>
                  
      <li>
    
                          <a href="iiif-api.html" title="The digilib IIIF API">
          <i class="none"></i>
        The digilib IIIF API</a>
            </li>
                  
      <li>
    
                          <a href="client-integration.html" title="Integrating digilib into your page">
          <i class="none"></i>
        Integrating digilib into your page</a>
            </li>
                  
      <li>
    
                          <a href="plugins.html" title="Digilib plugins">
          <i class="none"></i>
        Digilib plugins</a>
            </li>
                              <li class="nav-header">Project Documentation</li>
                                                                                                                                                          
      <li>
    
                          <a href="project-info.html" title="Project Information">
          <i class="icon-chevron-right"></i>
        Project Information</a>
                  </li>
            </ul>
                
                    
                
          <hr class="divider" />

           <div id="poweredBy">
                            <div class="clear"></div>
                            <div class="clear"></div>
                            <div class="clear"></div>
                                                                                                                   <a href="http://maven.apache.org/" title="Built by Maven" class="builtBy">
        <img class="builtBy"  alt="Built by Maven" src="https://maven.apache.org/images/logos/maven-feather.png"    />
      </a>
                                                                                                    <a href="../../" title="Hosted by GitHub" class="builtBy">
        <img class="builtBy"  alt="Hosted by GitHub" src="https://assets-cdn.github.com/images/modules/logos_page/GitHub-Logo.png"   width="200px"  />
      </a>
                                                                                                    <a href="http://www.sourceforge.net/" title="Hosted by SourceForge" class="builtBy">
        <img class="builtBy"  alt="Hosted by SourceForge" src="https://upload.wikimedia.org/wikipedia/commons/0/0b/Sourceforge_logo.png"    />
      </a>
                      </div>
          </div>
        </div>
        
                
        <div id="bodyColumn"  class="span9" >
                                  
            <h1>Configuring digilib</h1>
<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>
<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>
<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>

<div class="source">
<div class="source">
<pre>&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
&lt;digilib-config&gt;
    &lt;parameter name=&quot;basedir-list&quot; value=&quot;/usr/local/images&quot; /&gt;
&lt;/digilib-config&gt;
</pre></div></div>
<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>
<div class="section">
<h2><a name="Available_parameters"></a>Available parameters</h2>
<p>The documented parameter values below are the defaults.</p>
<p>If relative paths are provided as file locations, these will be resolved with the web application&#x2019;s directory as base.</p>
<p>You can inspect a summary of your running digilib configuration at the URL <tt>&lt;base_url&gt;/server/dlConfig.jsp</tt> e.g. <a class="externalLink" href="http://localhost:8080/digilib/server/dlConfig.jsp">http://localhost:8080/digilib/server/dlConfig.jsp</a>.</p>
<div class="section">
<h3><a name="Image_locations"></a>Image locations</h3>

<div class="source">
<div class="source">
<pre>&lt;parameter name=&quot;basedir-list&quot; value=&quot;sample-images&quot; /&gt;
</pre></div></div>
<p>A list of directories where images are searched. See <a href="image-directories.html">this document</a> for details (<b>required</b>).</p>

<div class="source">
<div class="source">
<pre>&lt;parameter name=&quot;denied-image&quot; value=&quot;img/digilib-denied.png&quot; /&gt;
</pre></div></div>
<p>This image is sent to indicate an authorization failure.</p>

<div class="source">
<div class="source">
<pre>&lt;parameter name=&quot;error-image&quot; value=&quot;img/digilib-error.png&quot; /&gt;
</pre></div></div>
<p>This image is sent to indicate a general failure.</p>

<div class="source">
<div class="source">
<pre>&lt;parameter name=&quot;notfound-image&quot; value=&quot;img/digilib-notfound.png&quot; /&gt;
</pre></div></div>
<p>This image to sent to indicate that the requested image does not exist or could not be read.</p>

<div class="source">
<div class="source">
<pre>&lt;parameter name=&quot;use-mapping&quot; value=&quot;false&quot; /&gt;
</pre></div></div>
<p>Enables the mapping of &#x2018;virtual directories&#x2019; to actual directories in the filesystem using a mapping file.</p>

<div class="source">
<div class="source">
<pre>&lt;parameter name=&quot;mapping-file&quot; value=&quot;digilib-map.xml&quot; /&gt;
</pre></div></div>
<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>
<p>The file contains <tt>mapping</tt> elements with a <tt>link</tt> attribute containing a &#x2018;virtual directory&#x2019; name that is redirected to the directory given in the <tt>dir</tt> attribute.</p></div>
<div class="section">
<h3><a name="Image_processing_options"></a>Image processing options</h3>

<div class="source">
<div class="source">
<pre>&lt;parameter name=&quot;default-quality&quot; value=&quot;2&quot; /&gt;
</pre></div></div>
<p>The default interpolation quality.</p>

<ul>
  
<li><tt>0</tt>: do not use interpolation (worst),</li>
  
<li><tt>1</tt>: use linear interpolation,</li>
  
<li><tt>2</tt>: use bilinear interpolation and blur-before-scale (best).</li>
</ul>

<div class="source">
<div class="source">
<pre>&lt;parameter name=&quot;max-image-size&quot; value=&quot;0&quot; /&gt;
</pre></div></div>
<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>

<div class="source">
<div class="source">
<pre>&lt;parameter name=&quot;sendfile-allowed&quot; value=&quot;true&quot; /&gt;
</pre></div></div>
<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>

<div class="source">
<div class="source">
<pre>&lt;parameter name=&quot;subsample-minimum&quot; value=&quot;2.0&quot; /&gt;
</pre></div></div>
<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>
<div class="section">
<h3><a name="Authentication_and_authorization"></a>Authentication and authorization</h3>
<p>Details are provided in the <a href="auth.html">documentation on authentication and authorization</a>.</p>

<div class="source">
<div class="source">
<pre>&lt;parameter name=&quot;use-authorization&quot; value=&quot;false&quot; /&gt;
</pre></div></div>
<p>Enables or disables all authorization. If <tt>use-authorization</tt> is <tt>true</tt> you also have to configure <tt>authnops-class</tt>, <tt>authzops-class</tt> and the <tt>auth-file</tt> and its contents.</p>

<div class="source">
<div class="source">
<pre>&lt;parameter name=&quot;auth-file&quot; value=&quot;digilib-auth.xml&quot; /&gt;
</pre></div></div>
<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>

<div class="source">
<div class="source">
<pre>&lt;parameter name=&quot;authn-token-cookie&quot; value=&quot;id_token&quot; /&gt;
</pre></div></div>
<p>The name of the cookie that holds the authentication token for <tt>digilib.auth.OpenIdAuthnOps</tt>.</p>

<div class="source">
<div class="source">
<pre>&lt;parameter name=&quot;authnops-class&quot; value=&quot;digilib.auth.IpAuthnOps&quot; /&gt;
</pre></div></div>
<p>The class to handle authentication.</p>

<div class="source">
<div class="source">
<pre>&lt;parameter name=&quot;authzops-class&quot; value=&quot;digilib.auth.PathAuthzOps&quot; /&gt;
</pre></div></div>
<p>The class to handle authorization.</p></div>
<div class="section">
<h3><a name="IIIF_API_options"></a>IIIF API options</h3>
<p>The options configure the IIIF interface. For more information see the <a href="iiif-api">digilib IIIF documentation</a></p>

<div class="source">
<div class="source">
<pre>&lt;parameter name=&quot;iiif-api-version&quot; value=&quot;2.1&quot; /&gt;
</pre></div></div>
<p>The IIIF API version for the generated <tt>info.json</tt> information response. </p>

<div class="source">
<div class="source">
<pre>&lt;parameter name=&quot;iiif-info-cors&quot; value=&quot;true&quot; /&gt;
</pre></div></div>
<p>Enables the <tt>Cross-Origin Resource Sharing</tt> header in IIIF info requests.</p>

<div class="source">
<div class="source">
<pre>&lt;parameter name=&quot;iiif-image-cors&quot; value=&quot;true&quot; /&gt;
</pre></div></div>
<p>Enables the <tt>Cross-Origin Resource Sharing</tt> header in IIIF image requests.</p>

<div class="source">
<div class="source">
<pre>&lt;parameter name=&quot;iiif-prefix&quot; value=&quot;IIIF&quot; /&gt;
</pre></div></div>
<p>The prefix (after <tt>Scaler</tt>) that leads to the IIIF API.</p>

<div class="source">
<div class="source">
<pre>&lt;parameter name=&quot;iiif-slash-replacement&quot; value=&quot;!&quot; /&gt;
</pre></div></div>
<p>The character that replaces a slash in the identifier of IIIF requests.</p></div>
<div class="section">
<h3><a name="Threading_options"></a>Threading options</h3>

<div class="source">
<div class="source">
<pre>&lt;parameter name=&quot;max-waiting-threads&quot; value=&quot;20&quot; /&gt;
</pre></div></div>
<p>The maximum number of requests waiting in the queue before new requests get &#x201c;service unavailable&#x201d;.</p>

<div class="source">
<div class="source">
<pre>&lt;parameter name=&quot;worker-threads&quot; value=&quot;2&quot; /&gt;
</pre></div></div>
<p>The maximum number of concurrently working threads.</p>

<div class="source">
<div class="source">
<pre>&lt;parameter name=&quot;worker-timeout&quot; value=&quot;60000&quot; /&gt;
</pre></div></div>
<p>Timeout for worker threads in milliseconds.</p></div>
<div class="section">
<h3><a name="Other_options"></a>Other options</h3>

<div class="source">
<div class="source">
<pre>&lt;parameter name=&quot;default-errmsg-type&quot; value=&quot;image&quot; /&gt;
</pre></div></div>
<p>Defines how errors are presented to the user. Allowed values are <tt>code</tt>, <tt>image</tt> and <tt>text</tt>.</p>

<ul>
  
<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>
  
<li><tt>code</tt> sends an HTTP error code, which may result in a broken image display in the browser.</li>
  
<li><tt>text</tt> sends a plain-text error message, which may result in a broken image display in the browser.</li>
</ul>

<div class="source">
<div class="source">
<pre>&lt;parameter name=&quot;img-diskcache-allowed&quot; value=&quot;false&quot; /&gt;
</pre></div></div>
<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>

<div class="source">
<div class="source">
<pre>&lt;parameter name=&quot;log-config-file&quot; value=&quot;log4j-config.xml&quot; /&gt;
</pre></div></div>
<p>Location of the logging configuration file. The current logging library is <a class="externalLink" href="https://logging.apache.org/log4j/1.2/manual.html">Log4J 1.2</a>.</p></div>
<div class="section">
<h3><a name="Options_for_developers"></a>Options for developers</h3>
<p>Using these options you can replace default classes used by digilib with your own implementations to change the behaviour of digilib. </p>

<div class="source">
<div class="source">
<pre>&lt;parameter name=&quot;docuimage-class&quot; value=&quot;digilib.image.ImageLoaderDocuImage&quot; /&gt;
</pre></div></div>
<p>Class of the <tt>DocuImage</tt> instance. You can replace the <tt>digilib.image.DocuImage</tt> implementation to use a different image toolkit than Java ImageIO. (There are deprecated alternative implementations in the <tt>common-jai</tt>, <tt>common-imagej</tt> and <tt>common-bioformats</tt> modules.) </p>

<div class="source">
<div class="source">
<pre>&lt;parameter name=&quot;docuimage-hacks&quot; value=&quot;&quot; /&gt;
</pre></div></div>
<p>Text string to selectively enable specific <tt>Hacks</tt> in the <tt>DocuImage</tt> implementation (see <a class="externalLink" href="https://github.com/robcast/digilib/blob/master/common/src/main/java/digilib/image/ImageLoaderDocuImage.java">the source</a>)</p>

<div class="source">
<div class="source">
<pre>&lt;parameter name=&quot;filemeta-class&quot; value=&quot;digilib.meta.IndexMetaFileMeta&quot; /&gt;
&lt;parameter name=&quot;dirmeta-class&quot; value=&quot;digilib.meta.IndexMetaDirMeta&quot; /&gt;
</pre></div></div>
<p>Classes of the <tt>digilib.meta.FileMeta</tt> and <tt>digilib.meta.DirMeta</tt> implementations. You can change these implementations to change the way digilib finds metadata about image files.</p>
<p><tt>IndexMetaFileMeta</tt> and <tt>IndexMetaDirMeta</tt> read metadata from <tt>index.meta</tt> and <tt>*.meta</tt> XML files according to the <a class="externalLink" href="http://intern.mpiwg-berlin.mpg.de/digitalhumanities/mpiwg-metadata-documentation/formate/indexmeta-standard">index meta standard</a>.</p>

<div class="source">
<div class="source">
<pre>&lt;parameter name=&quot;docudirectory-class&quot; value=&quot;digilib.io.BaseDirDocuDirectory&quot; /&gt;
</pre></div></div>
<p>Class of the <tt>digilib.io.DocuDirectory</tt> implementation. You can change this implementation to change the way digilib finds image files (including different resolutions).</p></div></div>
                  </div>
            </div>
          </div>

    <hr/>

    <footer>
            <div class="container-fluid">
              <div class="row span12">Copyright &copy;                    2001-2017
                        <a href="https://robcast.github.io/digilib/">digilib Community</a>.
            All Rights Reserved.      
                    
      </div>

        
        
                </div>
    </footer>
  </body>
</html>