Page History
...
For ease of use, the Configuration documentation is broken into several parts:
- General Configuration 81952888 - addresses general conventions used with configuring the
local.cfg
file,dspace.cfg
and other configuration files which use similar conventions. - The local.cfg Configuration Properties File 81952888 - describes how to use the
local.cfg
file to store all your locally customized configurations - The dspace.cfg Configuration Properties File 81952888 - specifies the basic
dspace.cfg
file settings (these settings specify the default configuration for DSpace) Optional or Advanced Configuration Settings 81952888 - contain other more advanced settings that are optional in the
dspace.cfg
configuration file.
...
[dspace]/config/dspace.cfg
: The primary configuration file, which contains the main configurations for DSpace.[dspace]/config/modules/*.cfg
: Module configuration files, which are specific to various modules/features within DSpace.[dspace]/config/local.cfg
: A (optional, but highly recommended) localized copy of configurations/settings specific to your DSpace (see The local.cfg Configuration Properties File 81952888 below)- Additional feature-specific configuration files also exist under
[dspace]/config/
, some of these include:default.license
: the default deposit license used by DSpace during the submission process (see Submission User Interface documentation)hibernate.cfg.xml
: The Hibernate class configuration for the DSpace database (almost never requires changing)input-forms.xml
: The default deposit input forms for DSpace (see Submission User Interface documentation)item-submission.xml
: the default item submission process for DSpace (see Submission User Interface documentation)launcher.xml
: The configuration of the DSpace command-line "launcher" ([dspace]/bin/dspace
, see the DSpace Command Launcher documentation)log4j.properties
: The default logging settings for DSpace log files (usually placed in[dspace]/log
)news-side.html
andnews-top.html
: HTML news configuration files for the JSPUI homepage (see JSPUI Configuration and Customization)news-xmlui.xml
: News configuration file for the XMLUI homepage (see XMLUI Configuration and Customization)workflow.xml
: Configuration for the Configurable Workflow feature (not used by default)xmlui.xconf
: Configuration for the XMLUI (see XMLUI Configuration and Customization)
...
Additionally, DSpace provides the ability to easily override default configuration settings (in dspace.cfg or modules/*.cfg) using a local.cfg file (see The local.cfg Configuration Properties File81952888) or using System Properties / Environment Varilables.
...
- Configuration File Syntax/Sources: All DSpace configurations are loaded via Properties files (using the Configuration File Syntax 81952888 detailed above)
- Note: Apache Commons Configuration does support other configuration sources such as XML configurations or database configurations (see its Overview documentation). At this time, DSpace does not utilize these other sorts of configurations by default. However, it would be possible to customize your local config-definition.xml to load settings from other locations.
- Configuration Files/Sources: By default, only two configuration files are loaded into Apache Commons Configuration for DSpace:
local.cfg
(see The local.cfg Configuration Properties File 81952888 documentation below)dspace.cfg
(NOTE: allmodules/*.cfg
are loaded bydspace.cfg
via "include=
" statements at the end of that configuration file. They are essentially treated as sub-configs which are embedded/included into thedspace.cfg
)
- Configuration Override Scheme: The configuration override scheme is defined as follows. Configurations specified in earlier locations will automatically override any later values:
- System Properties (
-D[setting]=[value]
) override all other options - Environment Variables
local.cfg
dspace.cfg
(and allmodules/*.cfg
files) contain the default values for all settings.
- System Properties (
- Configuration Auto-Reload: By default, all configuration files are automatically checked every 5 seconds for changes. If they have changed, they are automatically reloaded.
...
- Override any default configurations: Any setting in your
local.cfg
will automatically OVERRIDE a setting of the same name in thedspace.cfg
or anymodules/*.cfg
file. This also means that you can copy ANY configuration (fromdspace.cfg
or anymodules/*.cfg
file) into your local.cfg
to specify a new value.- For example, specifying
dspace.url
inlocal.cfg
will override the default value ofdspace.url
indspace.cfg
. - Also, specifying
oai.solr.url
inlocal.cfg
will override the default value ofoai.solr.url
inconfig/modules/oai.cfg
- For example, specifying
- Configuration Syntax: The
local.cfg
file uses the Apache Commons Configuration Property file syntax (like all *.cfg files) . For more information see the section on Configuration File Syntax 81952888 above.- This means the
local.cfg
also supports enhanced features like the ability to include other config files (via "include=
" statements).
- This means the
- Override local.cfg via System Properties: As needed, you also are able to OVERRIDE settings in your
local.cfg
by specifying them as System Properties or Environment Variables.- For example, if you wanted to change your
dspace.dir
in development/staging environment, you could specify it as a System Property (e.g.-Ddspace.dir=[new-location]
). This new value will override any value in bothlocal.cfg
anddspace.cfg
.
- For example, if you wanted to change your
When you build DSpace (e.g. mvn package), this local.cfg
file will be automatically copied to [dspace]/config/local.cfg
. Similar to the dspace.cfg
, the "runtime" configuration (used by DSpace) is the one in [dspace]/config/local.cfg
. See the Why are there multiple copies of some config files? 81952888 question above for more details on the runtime vs source configuration.
...
Info | ||
---|---|---|
| ||
Remember, any of the below |
...
DSpace will look up a javax.mail.Session object in JNDI and, if found, will use that to send email. Otherwise it will create a Session using some of the properties detailed below.
Property: |
|
Example Value: |
|
Informational Note: | The address on which your outgoing SMTP email server can be reached. |
Property: |
|
Example Value: |
|
Informational Note: | SMTP mail server authentication username, if required. This property is optional. |
Property: |
|
Example Value: |
|
Informational Note: | SMTP mail server authentication password, if required. This property is optional |
. | |||
Property: |
| ||
Example Value: |
| ||
Informational Note: | The port on which your SMTP mail server can be reached. By default, port 25 is used, port 587 is commonly used for TLS connections. Change this setting if your SMTP mailserver is running on another port. This property is optional. | ||
Property: |
| ||
Example Value: |
| ||
Informational Note: | The "From" address for email. Change the 'myu.edu' to the site's host name. | ||
Property: |
| ||
Example Value: |
| ||
Informational Note: | When a user clicks on the feedback link/feature, the information will be sent to the email address of choice. This configuration is currently limited to only one recipient. Since DSpace 4.0, this is also the email address displayed on the contacts page. | ||
Property: |
| ||
Example Value: |
| ||
Informational Note: | Email address of the general site administrator (Webmaster) | ||
Property: |
| ||
Example Value: |
| ||
Informational Note: | Enter the recipient for server errors and alerts. This property is optional. | ||
Property: |
| ||
Example Value: |
| ||
Informational Note: | Enter the recipient that will be notified when a new user registers on DSpace. This property is optional. | ||
Property: |
| ||
Example Value: |
| ||
Informational Note: | Set the default mail character set. This may be over-ridden by providing a line inside the email template 'charset: <encoding>', otherwise this default is used. | ||
Property: |
| ||
Example Value: |
| ||
Informational Note: | A comma separated list of hostnames that are allowed to refer browsers to email forms. Default behavior is to accept referrals only from dspace.hostname. This property is optional. | ||
Property: |
| ||
Example Value: |
| ||
Informational Note: | If you need to pass extra settings to the Java mail library. Comma separated, equals sign between the key and the value. This property is optional. | ||
Property: |
| ||
Example Value: |
| ||
Informational Note: | An option is added to disable the mailserver. By default, this property is set to ' | ||
Property: |
| ||
Example Value: |
| ||
Informational Note: | Specifies the name of a javax.mail.Session object stored in JNDI under | ||
Property: |
| ||
Example Value: |
| ||
Informational Note: | If no other language is explicitly stated in the input-forms.xml, the default language will be attributed to the metadata values. |
Wording of E-mail Messages
...
- A line beginning with "#" is a comment and will not be included in the message.
- A line beginning with "Subject: " will set the
Subject:
header of the message and will not be included in the body. - A line beginning with "Charset: " will set the character set in which the subject and single message bodypart are assumed to be encoded, will be used as the value of the
charset
parameter of theContent-Encoding
header for the message, and will not be included in the body. If the message has multiple bodyparts (i.e. attachments are included) then all are assumed to be encoded in US-ASCII and the "Charset: " line has no effect on them (but still affects the subject). A number enclosed in braces, such as
{2}
, anywhere in a non-comment line, will be replaced with the corresponding parameter which was supplied to the message when the message formatter was called. Parameter numbers are 0-based. Refer to the comments in the template or to the code which uses it for the meaning of each parameter.
Using an external mail server
If you want to use an external mail server setting the value of mail.server
to the domain name is enough if authentication is not required. Most external SMTP mail servers will however require authentication for obvious reasons. To enable TLS encryption you will typically have to set the mail.server.port
to the secure default 587 and for the mail.server.username
and mail.server.password
to be set. In addition you will need to enable TLS by setting the following extra properties:
Code Block |
---|
mail.extraproperties = mail.smtp.auth=true, \
mail.smtp.starttls.enable=true |
File Storage
Info |
---|
Beginning with DSpace 6, your file storage location (aka bitstore) is now defined in the |
...
Property: | webui.submission.sherparomeo-policy-enabled |
Example Value: | webui.submission.sherparomeo-policy-enabled = true |
Informational Note: | Controls whether or not the UI submission should try to use the Sherpa/RoMEO Publishers Policy Database Integration (default true) |
Property: | sherpa.romeo.url |
Example Value: | sherpa.romeo.url = http://www.sherpa.ac.uk/romeo/api29.php |
Informational Note: | The Sherpa/RoMEO endpoint. Shared with the authority control feauture for Journal Title autocomplete see AuthorityControlSettings 81952888 |
Property: | sherpa.romeo.apikey |
Example Value: | sherpa.romeo.apikey = YOUR-API-KEY |
Informational Note: | Allow to use a specific API key to raise the usage limit (500 calls/day for unregistred user). You can register for a free api access key at http://www.sherpa.ac.uk/news/romeoapikeys.htm |
The functionality rely on understanding to which Journal (ISSN) is related the submitting item. This is done out of box looking to some item metadata but a different strategy can be used as for example look to a metadata authority in the case that the Sherpa/RoMEO autocomplete for Journal is used (see AuthorityControlSettings 81952888)
The strategy used to discover the Journal related to the submission item is defined in the spring file /config/spring/api/sherpa.xml
...
Property: |
|
Example Value: |
|
Informational Note: | This is an example of how one "Defines the Indexes". See "Defining the Indexes81952888" in the next sub-section. |
Property: |
|
Example Value: |
|
Informational Note: | This is an example of how one "Defines the Sort Options". See "Defining Sort Options81952888" in the following sub-section. |
...
Element | Definition and Options (if available) |
---|---|
| n is the index number. The index numbers must start from 1 and increment continuously by 1 thereafter. Deviation from this will cause an error during install or a configuration update. So anytime you add a new browse index, remember to increase the number. (Commented out index numbers may be used over again). |
| The name by which the index will be identified. In order for the DSpace UI to display human-friendly description for this index, you'll need to update either your Messages.properties (JSPUI) or messages.xml (XMLUI) with new message keys referencing this <index-name>. JSPUI Example (Messages.properties):
XMLUI Example (messages.xml):
|
| Only two options are available: "
|
| (Only for "metadata" indexes) The schema used for the field to be index. The default is dc (for Dublin Core). |
| (Only for "metadata" indexes) The schema element. In Dublin Core, for example, the author element is referred to as "Contributor". The user should consult the default Dublin Core Metadata Registry table in Appendix A. |
| (Only for "metadata" indexes) This is the qualifier to the <element> component. The user has two choices: an asterisk "" or a proper qualifier of the element. The asterisk is a wildcard and causes DSpace to index all types of the schema element. For example, if you have the element "contributor" and the qualifier "" then you would index all contributor data regardless of the qualifier. Another example, you have the element "subject" and the qualifier "lcsh" would cause the indexing of only those fields that have the qualifier "lcsh". (This means you would only index Library of Congress Subject Headings and not all data elements that are subjects. |
| (Optional, should be set for "item" indexes) This refers to the sort type / data type of the field:
|
| (Optional) The default sort order. Choose |
...
Element | Definition and Options (if available) |
---|---|
| n is an arbitrary number you choose. |
| The name by which the sort option will be identified. This is the name by which it is referred in the "webui.browse.index" settings (see Defining the Indexes 81952888). |
| The schema used for the field to be sorted on in the index. The default is dc (for Dublin Core). |
| The schema element. In Dublin Core, for example, the author element is referred to as "Contributor". The user should consult the default Dublin Core Metadata Registry table in Appendix A. |
| This is the qualifier to the <element> component. The user has two choices: an asterisk "*" or a proper qualifier of the element. |
| This refers to the datatype of the field: |
...
Property: |
| ||
Example Value: |
| ||
Informational Note: |
| ||
Property: |
| ||
Example Value: |
| ||
Property: |
| ||
Example Value: |
The Linked Data Service at the Library of Congress might be a better, and more stable, option: http://id.loc.gov/authorities/names.html | ||
Informational Note: | Location (URL) of the Library of Congress Name Service | ||
Property: |
| ||
Informational Note: | Please refers to the Sherpa/RoMEO Publishers Policy Database Integration section for details about such properties. See Configuring the Sherpa/RoMEO Publishers Policy Database Integration | ||
Property: |
| ||
Example Value: | orcid.api.url = https://pub.orcid.org/v2.1 | ||
Informational Note: | Location (URL) of the ORCID v2 Public API | ||
Property: |
| ||
Example Value: |
| ||
Informational Note: | This sets the default lowest confidence level at which a metadata value is included in an authority-controlled browse (and search) index. It is a symbolic keyword, one of the following values (listed in descending order): accepted, uncertain, ambiguous, notfound, failed, rejected, novalue, unset. See | ||
Property: |
| ||
Example Value: |
| ||
Informational Note: | This property sets the number of selectable choices in the Choices lookup popup |
...