Mercurial > hg > digilib

comparison doc/src/site/markdown/digilib-config.md @ 1658:28df291d4e26

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Updated documentation. Updated build and install instructions to be simpler and hopefully more clear. Updated @funkyfuture's refactored configuration docs (still lots TODO). Added @funkyfuture's server-setup docu to menu. Renamed non-minified digilib-dbg.html to digilib-dev.html
author Robert Casties <r0bcas7@gmail.com>
date Mon, 20 Nov 2017 21:08:35 +0100
parents 7310735dd5b5
children 6420df6b213b
comparison
equal deleted inserted replaced
1657:fb211930d6e8 1658:28df291d4e26
1 # Configuring digilib 1 # Configuring digilib
2 2
3 The main configuration for *digilib* is the XML file `digilib-config.xml` in the 3 The main configuration for *digilib* is the XML file `digilib-config.xml` in the
4 `WEB-INF` directory of the webapp or a Java properties file `digilib.properties` 4 `WEB-INF` directory of the webapp. Alternatively you can also use a Java properties
5 somewhere in the classpath. 5 file `digilib.properties` somewhere in the classpath.
6 (If you really need a different location for the XML file you can define it in 6 (If you really need a different location for the XML file you can define it in
7 the `config-file` init-parameter to the Servlet. **TODO** add an example) 7 the `config-file` init-parameter to the Servlet. **TODO** add an example)
8 8
9 In the configuration file you can set lots of paths and options. *digilib* uses 9 In the configuration file you can set lots of paths and options. *digilib* uses
10 default values for all configuration settings that meet most requirements. 10 default values for all configuration settings that meet most requirements.
11 Hence you have to configure only the settings that you want to change. The 11 Hence you have to configure only the settings that you want to change. The
12 **`basedir-list`** parameter however is **mandatory** unless you want to serve 12 **`basedir-list`** parameter however is **mandatory** unless you only want to serve
13 the contributed example images for an evaluation. 13 the contributed example images for an evaluation.
14 14
15 All options are defined as `parameter` elements with the attributes `name` and 15 All options are defined as `parameter` elements with the attributes `name` and
16 `value` that are wrapped in the root element `digilib-config`. A minimal 16 `value` that are wrapped in the root element `digilib-config`. A minimal
17 configuration looks like this: 17 configuration looks like this:
60 60
61 ```xml 61 ```xml
62 <parameter name="notfound-image" value="img/digilib-notfound.png" /> 62 <parameter name="notfound-image" value="img/digilib-notfound.png" />
63 ``` 63 ```
64 64
65 This image to sent to indicate an undiscoverable image. 65 This image to sent to indicate that the requested image does not exist or could not be read.
66 66
67 ```xml 67 ```xml
68 <parameter name="use-mapping" value="false" /> 68 <parameter name="use-mapping" value="false" />
69 ``` 69 ```
70 70
71 Enables the mapping of 'virtual directories' to actual directories in the 71 Enables the mapping of 'virtual directories' to actual directories in the
72 filesystem. 72 filesystem using a mapping file.
73 73
74 ```xml 74 ```xml
75 <parameter name="mapping-file" value="digilib-map.xml" /> 75 <parameter name="mapping-file" value="digilib-map.xml" />
76 ``` 76 ```
77 77
78 The location of the mapping file. Refer to 78 The location of the mapping file. Refer to
79 [this template](https://sourceforge.net/p/digilib/code/ci/default/tree/webapp/src/main/webapp/WEB-INF/digilib-map.xml.template) 79 [digilib-map.xml.template](https://github.com/robcast/digilib/blob/master/webapp/src/main/webapp/WEB-INF/digilib-map.xml.template)
80 for an example. **TODO** elaborate `link` and `dir` attribute or the whole file structure. 80 for an example.
81
82 The file contains `mapping` elements with a `link` attribute containing a 'virtual directory' name that is mapped to the
83 directory given in the `dir` attribute.
81 84
82 85
83 ### Image processing options 86 ### Image processing options
84 87
85 ```xml 88 ```xml
86 <parameter name="default-quality" value="2" /> 89 <parameter name="default-quality" value="2" />
87 ``` 90 ```
88 91
89 The default interpolation quality (`0` is worst). 92 The default interpolation quality.
90 93
91 **TODO** document valid value range 94 * `0`: do not use interpolation (worst),
95 * `1`: use linear interpolation,
96 * `2`: use bilinear interpolation and blur-before-scale (best).
92 97
93 ```xml 98 ```xml
94 <parameter name="max-image-size" value="0" /> 99 <parameter name="max-image-size" value="0" />
95 ``` 100 ```
96 101
97 The maximum size of delivered images, `0` means no limit. 102 The maximum size of delivered images as pixel area, `40000` means up to 200x200 or 100x400, `0` means no limit.
98
99 **TODO** mention measurement unit explicitly
100 103
101 ```xml 104 ```xml
102 <parameter name="sendfile-allowed" value="true" /> 105 <parameter name="sendfile-allowed" value="true" />
103 ``` 106 ```
104 107
105 Defines whether requests with `mo=file` as parameter are allowed (see 108 Defines whether requests with `mo=file` or `mo=rawfile` as parameter are allowed to download files (see
106 [Scaler API](scaler-api.html)). 109 [Scaler API](scaler-api.html)).
107 110
108 ```xml 111 ```xml
109 <parameter name="subsample-minimum" value="2.0" /> 112 <parameter name="subsample-minimum" value="2.0" />
110 ``` 113 ```
111 114
112 Degree of subsampling on image load. **TODO** valid / recommended value range 115 Degree of subsampling on image load. This is the minimum factor that is scaled by interpolation and not by
116 subsampling, i.e. by skipping pixels.
113 117
114 118
115 ### Authentication and authorization 119 ### Authentication and authorization
116 120
117 Details are provided in the 121 Details are provided in the
119 123
120 ```xml 124 ```xml
121 <parameter name="auth-file" value="digilib-auth.xml" /> 125 <parameter name="auth-file" value="digilib-auth.xml" />
122 ``` 126 ```
123 127
124 Configuration file for authentication and authorization. 128 Configuration file for authentication and authorization. The format and content of the configuration file
125 129 is determined by the chosen authentication and authorization classes.
126 ```xml
127 <parameter name="auth-url-path" value="authenticated/" />
128 ```
129
130 This part of the URL indicates authorized access. **TODO** clarify by example?
131 130
132 ```xml 131 ```xml
133 <parameter name="authn-token-cookie" value="id_token" /> 132 <parameter name="authn-token-cookie" value="id_token" />
134 ``` 133 ```
135 134
136 The name of the cookie that holds the authentication token. 135 The name of the cookie that holds the authentication token for `digilib.auth.OpenIdAuthnOps`.
137 136
138 ```xml 137 ```xml
139 <parameter name="authnops-class" value="digilib.auth.IpAuthnOps" /> 138 <parameter name="authnops-class" value="digilib.auth.IpAuthnOps" />
140 ``` 139 ```
141 140
149 148
150 ```xml 149 ```xml
151 <parameter name="use-authorization" value="false" /> 150 <parameter name="use-authorization" value="false" />
152 ``` 151 ```
153 152
154 Enables authorization. 153 Enable or disable all authorization. If `use-authorization` is `true` it also needs to be configured
154 using `authnops-class` and `authzops-class` and the `auth-file`.
155 155
156 156
157 ### IIIF API options 157 ### IIIF API options
158 158
159 The options configure the [IIIF](iiif-api) interface. 159 The options configure the IIIF interface. For more information see the [digilib IIIF documentation](iiif-api)
160 160
161 ```xml 161 ```xml
162 <parameter name="iiif-api-version" value="2.1" /> 162 <parameter name="iiif-api-version" value="2.1" />
163 ``` 163 ```
164 164
165 The supported IIIF API version. **FIXME**? shouldn't that be set programmatically? 165 The IIIF API version for the generated `info.json` information response.
166 166
167 ```xml 167 ```xml
168 <parameter name="iiif-info-cors" value="true" /> 168 <parameter name="iiif-info-cors" value="true" />
169 ``` 169 ```
170 170
184 184
185 ```xml 185 ```xml
186 <parameter name="iiif-slash-replacement" value="!" /> 186 <parameter name="iiif-slash-replacement" value="!" />
187 ``` 187 ```
188 188
189 The character that replaces a slash in IIIF requests. 189 The character that replaces a slash in the identifier of IIIF requests.
190 190
191 191
192 ### Threading options 192 ### Threading options
193 193
194 ```xml 194 ```xml
195 <parameter name="max-waiting-threads" value="20" /> 195 <parameter name="max-waiting-threads" value="20" />
196 ``` 196 ```
197 197
198 The number of waiting requests in the queue. 198 The maximum number of requests waiting in the queue before sending "service unavailable".
199 199
200 ```xml 200 ```xml
201 <parameter name="worker-threads" value="2" /> 201 <parameter name="worker-threads" value="2" />
202 ``` 202 ```
203 203
204 The number of working threads. 204 The maximum number of concurrently working threads.
205 205
206 ```xml 206 ```xml
207 <parameter name="worker-timeout" value="60000" /> 207 <parameter name="worker-timeout" value="60000" />
208 ``` 208 ```
209 209
214 214
215 ```xml 215 ```xml
216 <parameter name="default-errmsg-type" value="image" /> 216 <parameter name="default-errmsg-type" value="image" />
217 ``` 217 ```
218 218
219 Defines how errors are represented. Allowed values are `code`, `image` and 219 Defines how errors are presented to the user. Allowed values are `code`, `image` and
220 `text`. 220 `text`.
221 221
222 * `image` sends an error-image as error code (see `denied-image`, `error-image`, `notfound-image` parameters).
223 * `code` sends an HTTP error code, which may result in a broken image display in the browser.
224 * `text` sends a plain-text error message, which may result in a broken image display in the browser.
225
222 ```xml 226 ```xml
223 <parameter name="img-diskcache-allowed" value="false" /> 227 <parameter name="img-diskcache-allowed" value="false" />
224 ``` 228 ```
225 229
226 Enables the use of a disk cache for the image toolkit. 230 Enables the use of a disk cache for the image toolkit. Using the disk cache may leak file handles
227 **TODO** elaborate dis-/advantages. 231 and lead to resource issues if digilib runs for a long time.
228 232
229 ```xml 233 ```xml
230 <parameter name="log-config-file" value="log4j-config.xml" /> 234 <parameter name="log-config-file" value="log4j-config.xml" />
231 ``` 235 ```
232 236
233 Location of the logging configuration. 237 Location of the logging configuration file. The current logger is
234 238 [Log4J 1.2](https://logging.apache.org/log4j/1.2/manual.html).
235 **TODO** amend a link to a useful, elaborative resource
236 239
237 240
238 ### Unknown category 241 ### Unknown category
239 242
240 **TODO** move items to appropriate sections 243 **TODO** move items to appropriate sections