DSpace System Documentation: Configuration and Customization

Back to contents

There are a number of ways in which DSpace can be configured and/or customized:

• Altering the configuration files in [dspace]/config
• Creating modified versions of the JSPs; these can be placed separately from and override the default installed JSPs, so that future updates of the code won't overwrite your changes
• Implementing a custom 'authenticator' class, so that user authentication in the Web UI can be adapted and integrated with any existing mechanisms your organization might use
• Editing the source code

Of these methods, only the last is likely to cause any headaches; if you update the DSpace source code directly, it may make applying future updates difficult. However, DSpace is open source, of course, and if you make any modifications that might be helpful to other institutions or organizations, feel free to send them to the DSpace team at MIT.

The dspace.cfg Configuration Properties File

The primary way of configuring DSpace is to edit the dspace.cfg. You'll definitely have to do this before you can operate DSpace properly. dspace.cfg contains basic information about a DSpace installation, including system path information, network host information, and other things like site name.

The default dspace.cfg is a good source of information, and contains comments for all properties. It's a basic Java properties file, where lines are either comments, starting with a '#', blank lines, or property/value pairs of the form:

property.name = property value

Due to time constraints, this document does not contain an exhaustive list of properties; they are all listed in the supplied dspace.cfg. Below are some particularly relevant properties with notes for their use:

Whenever you edit dspace.cfg, you should then run [dspace]/bin/install-configs so that any changes you may have made are reflected in the configuration files of other applications, for example Apache. You may then need to restart those applications, depending on what you changed.

Wording of E-mail Messages

Sometimes DSpace automatically sends e-mail messages to users, for example to inform them of a new workflow task, or as a subscription e-mail alert. The wording of emails can be changed by editing the relevant file in [dspace]/config/emails. Each file is commented. Be careful to keep the right number 'placeholders' (e.g.{2}).

Local DSpace Administrator Contact Information

There are several places in DSpace in which the user will be shown contact information for the local DSpace Administrator: for instance, when an error occurs, or in the on-line help when the user is looking for more information. The contact information is displayed by [dspace-source]/jsp/components/contact-info.jsp. This JSP retrieves the help e-mail in dspace.cfg, but the phone number in the JSP is a dummy phone number that needs to be edited directly in the JSP. You should be sure to edit this file (adding any additional information you feel might be useful) so that users know who to contact for further information.

The Dublin Core and Bitstream Format Registries

The [dspace]/config/registries directory contains two XML files. These are used to load the initial contents of the Dublin Core type registry and Bitstream Format registry. After the initial loading (performed by ant fresh_install above), the registries reside in the database; the XML files are not updated.

Currently, the system requires that every item have a Dublin Core record. The exact Dublin Core elements and qualifiers that are used can be configured by editing the Dublin Core registry. This can either be done at install-time, by editing [dspace]/config/registries/dublin-core-types.xml, or at run-time using the administration Web UI. However, note that some elements and qualifiers must be present for DSpace to function correctly since they are used for various purposes by the code. Details are in the relevant .xml file.

Also note that altering the Dublin Core registry does not, at the current time, cause corresponding changes in the Web UI (e.g. the submission interface or search indices).

The bitstream formats recognized by the system and levels of support are similarly stored in the bitstream format registry. This can also be edited at install-time via [dspace]/config/registries/bitstream-formats.xml or by the administation Web UI. The contents of the bitstream format registry are entirely up to you, though the system requires that the following two formats are present:

• Unknown
• License

Configuration Files for Other Applications

To ease the hassle of keeping configuration files for other applications involved in running a DSpace site, for example Apache, in sync, the DSpace system can automatically update them for you when the main DSpace configuration is changed. This feature of the DSpace system is entirely optional, but we found it useful.

The way this is done is by placing the configuration files for those applications in [dspace]/config/templates, and inserting special values in the configuration file that will be filled out with appropriate DSpace configuration properties. Then, tell DSpace where to put filled-out, 'live' version of the configuration by adding an appropriate property to dspace.cfg, and run [dspace]/bin/install-configs.

Take the apache13.conf file as an example. This contains plenty of Apache-specific stuff, but where it uses a value that should be kept in sync across DSpace and associated applications, a 'placeholder' value is written. For example, the host name:

ServerName @@dspace.hostname@@

The text @@dspace.hostname@@ will be filled out with the value of the dspace.hostname property in dspace.cfg. Then we decide where we want the 'live' version, that is, the version actually read in by Apache when it starts up, will go.

Let's say we want the live version to be located at /opt/apache/conf/dspace-httpd.conf. To do this, we add the following property to dspace.cfg so DSpace knows where to put it:

config.template.apache13.conf = /opt/apache/conf/dspace-httpd.conf

Now, we run [dspace]/bin/install-configs. This reads in [dspace]/config/templates/apache13.conf, and places a copy at /opt/apache/conf/dspace-httpd.conf with the placeholders filled out.

So, in /opt/apache/conf/dspace-httpd.conf, there will be a line like:

ServerName dspace.myu.edu

The advantage of this approach is that if a property like the hostname changes, you can just change it in dspace.cfg and run install-configs, and all of your tools' configuration files will be updated.

However, take care to make all your edits to the versions in [dspace]/config/templates! It's a wise idea to put a big reminder at the top of each file, since someone might unwittingly edit a 'live' configuration file which would later be overwritten.

Customizing the Web User Interface

The Web UI is implemented using Java Servlets which handle the business logic, and JavaServer Pages (JSPs) which produce the HTML pages sent to an end-user. Since the JSPs are much closer to HTML than Java code, altering the look and feel of DSpace is relatively easy.

To make it even easier, DSpace allows you to 'override' the JSPs included in the source distribution with modified versions, that are stored in a separate place, so when it comes to updating your site with a new DSpace release, your modified versions will not be overwritten.

However, note that the data (attributes) passed from an underlying Servlet to the JSP may change between versions, so you may have to modify your customized Servlet to deal with the new data.

The JSPs are stored in [dspace-source]/jsp. Place your edited version of a JSP in the [dspace-source]/jsp/local directory, with the same path as the original. If they exist, these will be used in preference to the distributed versions in [dspace-source]/jsp. For example:

Heavy use is made of a style sheet, in [dspace-source]/jsp/styles.css.jsp. If you make edits, call the local version [dspace-source]/jsp/local/styles.css.jsp, and it will be used automatically in preference to the default, as described above.

Fonts and colors can be easily changed using the stylesheet. The stylesheet is a JSP so that the user's browser version can be detected and the stylesheet tweaked accordingly.

The 'layout' of each page, that is, the top and bottom banners and the navigation bar, are determined by the JSPs [dspace-source]/jsp/layout/header-*.jsp and [dspace-source]/jsp/layout/footer-*.jsp. You can provide modified versions of these (in [dspace-source]/jsp/local/layout, or define more styles and apply them to pages by using the "style" attribute of the dspace:layout tag.

After you've customized your JSPs, you must rebuild the DSpace Web application. If you haven't already built and installed it, follow the install directions. Otherwise, follow the steps below:

1. Rebuild the dspace.war file by running the following command from your [dspace-source] directory:

   ant -Dconfig=[dspace]/config/dspace.cfg build_wars
   

2. Shut down Tomcat, and delete the existing [tomcat]/webapps/dspace directory.

3. Copy the new .war file to the Tomcat webapps directory:

   cp [dspace-source]/build/dspace.war [tomcat]/webapps
   

When you restart the web server you should see your customized JSPs.

Custom Authentication Code

Since many institutions and organizations have exisiting authentication systems, DSpace has been designed to allow these to be easily integrated. To do this, you can provide a custom class implementing the Java interface org.dspace.app.webui.SiteAuthenticator. These methods are invoked when various authentication-related events occur in the Web user interface.

The basic authentication procedure in the DSpace Web UI is this:

1. A request is received from an end-user's browser that, if fulfilled, would lead to an action requiring authorization taking place.
2. If the end-user is already authenticated:
   • If the end-user is allowed to perform the action, the action proceeds
   • If the end-user is NOT allowed to perform the action, an authorization error is displayed.

LDAP Authentication

If LDAP is enabled in the dspace.cfg file, then new users will be able to register by entering their username and password without being sent the registration token. If users do not have a username and password, then they can still register and login with just their email address the same way they do now.

If you want to give any special privileges to LDAP users, you will still need to extend the SiteAuthenticator class to automatically put people who have a netid into a special group. You might also want to give certain email addresses special privileges. Refer to the Custom Authentication Code section above for more information about how to do this.

Here is an explanation of what each of the different configuration parameters are for:

• ldap.enable
  This setting will enable or disable LDAP authentication in DSpace. With the setting off, users will be required to register and login with their email address. With this setting on, users will be able to login and register with their LDAP user ids and passwords.
• webui.ldap.autoregister
  This will turn LDAP autoregistration on or off. With this on, a new EPerson object will be created for any user who successfully authenticates against the LDAP server when they first login. With this setting off, the user must first register to get an EPerson object by entering their ldap username and password and filling out the forms.
• ldap.provider_url = ldap://ldap.myu.edu/o=myu.edu
  This is the url to your institution's ldap server. You may or may not need the /o=myu.edu part at the end. Your server may also require the ldaps:// protocol.
• ldap.id_field = uid
  This is the unique identifier field in the LDAP directory where the username is stored.
• ldap.object_context = ou=people,o=myu.edu
  This is the object context used when authenticating the user. It is appended to the ldap.id_field and username. For example uid=username,ou=people,o=myu.edu. You will need to modify this to match your ldap configuration.
• ldap.search_context = ou=people
  This is the search context used when looking up a user's ldap object to retrieve their data for autoregistering. With ldap.autoregister turned on, when a user authenticates without an EPerson object we search the ldap directory to get their name and email address so that we can create one for them. So after we have authenticated against uid=username,ou=people,o=byu.edu we now search in ou=people for filtering on [uid=username]. Often the ldap.search_context is the same as the ldap.object_context parameter. But again this depends on your ldap server configuration.
• ldap.email_field = mail
  This is the ldap object field where the user's email address is stored. "mail" is the default and the most common for ldap servers. If the mail field is not found the username will be used as the email address when creating the eperson obejct.
• ldap.surname_field = sn
  This is the ldap object field where the user's last name is stored. "sn" is the default and is the most common for ldap servers. If the field is not found the field will be left blank in the new eperson object.
• ldap.givenname_field = givenName
  This is the ldap object field where the user's given names are stored. I'm not sure how common the givenName field is in different ldap instances. If the field is not found the field will be left blank in the new eperson object.
• ldap.phone_field = telephoneNumber
  This is the field where the user's phone number is stored in the ldap directory. If the field is not found the field will be left blank in the new eperson object.

System Statistical Reports

Statistics for the system can be made available at http://www.mydspaceinstance.edu/statistics. To use the system statistics you will have to initialise them as per the installation documentation, but before you do so you need to perform the customisations discussed here in order to ensure that the reports are generated correctly.

Configuration File

Configuration for the statistics system are in [dspace]/config/dstat.cfg and the file should guide you to correctly filling in the details required. For the most part you will not need to change this file.

Customising Shell Scripts

To customise the supplied perl scripts to do monthly and general report generation it is necessary to modify the scripts themselves sightly. This is because these scripts were developed to speed up the process of using DStat at Edinburgh University Library and were not particularly intended for external use. They appear here for the convenience of others and in order to bridge the gap between the report generation and the inclusion of those reports into the DSpace UI, which is currently a clunky process.

In order to get these scripts to work for you, open each of the following in turn:

dstat-general
dstat-initial
dstat-monthly
dstat-report-general
dstat-report-initial
dstat-report-monthly

scripts eding with -general do the work for building reports spanning the entire history of the archive; scripts ending -initial are to initialise the reports by doing monthly reports from some start date up to the present; scripts ending -monthly generate a single monthly report for the current month. These scripts are just designed to make life easier, and are not particularly clever or elegant.

In each file you will find a section:

# Details used
################################################

... some perl ...

################################################

the perl between the lines of hashes defines the variables which will be used to do all of the processing in the report. The following explains what the variables mean and what they should be set to for each of the scripts

dstat-initial:
$out_prefix: prefix to place in front of each output file.
$out_suffix: suffix for output file. A date will be inserted between the prefix and suffix
$start_year: year to start back-analysing monthly logs from
$start_month: month to start back-analysing monthly logs from
$dsrun: path to your dsrun script, usually [dspace]/bin/dsrun
$out_directory: directory into which to place analysis files, for example [dspace]/bin/log/

dstat-monthly:
$out_prefix: prefix to place in front of each output file.
$out_suffix: suffix for output file. A date will be inserted between the prefix and suffix
$dsrun: path to your dsrun script, usually [dspace]/bin/dsrun
$out_directory: directory into which to place analysis files, for example [dspace]/bin/log/

dstat-general:
$out_prefix: prefix to place in front of each output file.
$out_suffix: suffix for output file. Today's date will be inserted between the prefix and suffix
$dsrun: path to your dsrun script, usually [dspace]/bin/dsrun
$out_directory: directory into which to place analysis files, for example [dspace]/bin/log/

dstat-report-initial:
$in_prefix: the prefix of the files generated by dstat-initial
$in_suffix: the suffix of the files generated by dstat-initial
$out_prefix: the report file prefix. Should be "report-" in order to work with DSpace UI
$out_suffix: the report file suffix. Should be ".html" in order to work with DSpace UI
$start_year: the start year used in dstat-initial
$start_month: the start month used in dstat-initial
$dsrun: path to your dsrun script, usually [dspace]/bin/dsrun
$in_directory: directory where analysis files were placed in dstat-initial
$out_directory: the live reports directory: [dspace]/reports/

dstat-report-monthly:
$in_prefix: the prefix of the files generated by dstat-monthly
$in_suffix: the suffix of the files generated by dstat-monthly
$out_prefix: the report file prefix. Should be "report-" in order to work with DSpace UI
$out_suffix: the report file suffix. Should be ".html" in order to work with DSpace UI
$dsrun: path to your dsrun script, usually [dspace]/bin/dsrun
$in_directory: directory where analysis files were placed in dstat-monthly
$out_directory: the live reports directory: [dspace]/reports/

dstat-report-general:
$in_prefix: the prefix of the files generated by dstat-general
$in_suffix: the suffix of the files generated by dstat-general
$out_prefix: the report file prefix. Should be "report-general-" in order to work with DSpace UI
$out_suffix: the report file suffix. Should be ".html" in order to work with DSpace UI
$dsrun: path to your dsrun script, usually [dspace]/bin/dsrun
$in_directory: directory where analysis files were placed in dstat-general
$out_directory: the live reports directory: [dspace]/reports/

If you want additional customisations, you will need to modify the lines which build the command to be executed and change the parameters passed to the java processes which actually carry out the analysis. For more information on these processes either build the javadocs or run:

[dspace]/bin/dsrun ac.ed.dspace.stats.LogAnalyser -help
[dspace]/bin/dsrun ac.ed.dspace.stats.ReportGenerator -help

Cron Jobs

In order that the reports should be generated regularly and thus kept up to date you should set up the following cron jobs:

#run stat analyses
0 1 * * * [dspace]/bin/stat-general
0 1 * * * [dspace]/bin/stat-monthly
0 2 * * * [dspace]/bin/stat-report-general
0 2 * * * [dspace]/bin/stat-report-monthly

Obviously, you should choose execution times which are most useful to you, and you should ensure that the -report- scripts run a short while after the analysis scripts to give them time to complete (a run of around 8 months worth of logs can take around 25 seconds to complete); the resulting reports will let you know how long analysis took and you can adjust your cron times accordingly.

• If the end-user is NOT authenticated, i.e. is accessing DSpace anonymously:

• The parameters etc. of the request are stored
• The startAuthentication method is invoked on the currently configured SiteAuthenticator implementation
• That startAuthentication might instantly authenticate the user somehow, or forward the request to some sort of log-in page--the parameters of the original request are safely stored and will be accessible after the log-in process has completed
• If authentication is successful, the original request is resumed from step 2. above.

Please see the SiteAuthenticator.java source file for information about each of the methods. The default implementation, org.dspace.app.webui.SimpleAuthenticator, is a simple implementation that implements these policies:

• Use of inbuilt e-mail address/password-based log-in. This is achieved by forwarding a request that is attempting an action requiring authorization to the password log-in servlet, /password-login. The password log-in servlet (org.dspace.app.webui.servlet.PasswordServlet contains code that will resume the original request if authentication is successful, as per step 3. described above.

• Users can register themselves (i.e. add themselves as e-people without needing approval from the administrators), and can set their own passwords when they do this

• Users are not members of any special (dynamic) e-person groups

Included in the source is the implementation of SiteAuthenticator used at MIT, edu.mit.dspace.MITAuthenticator. This implements a slightly more complex authentication mechanism:

• If an authentication user in an MIT user, they must log in using an X509 Web certificate. The certificate-login servlet, similar to the password-login servlet, authenticates users via these certificates, and if successful, resumes the original request just as the password log-in servlet would.

• MIT users are also automatically added to the special (dynamic) group called 'MIT Users' (which must be present in the system!). This allows us to create authorization policies for MIT users without having to manually maintain membership of the MIT users group.

• Anyone can register themselves, but MIT users doing this cannot set a password; they must use their X509 Web certificate to log in.

The X509 certificate login servlet has an extra feature: If the webui.cert.autoregister configuration property is true, it will automatically register the user with the system.

You could create a customized version of the password login servlet to perform a similar action. For example, if your organization uses Windows NT domain authentication, you could implement a version of PasswordServlet.java that validates against Windows NT authentication, and automatically adds an e-person record for new users. It is strongly recommended that you do not edit PasswordServlet but create a new servlet for this, so that future updates of the DSpace code do not overwrite your changes. You would also have to implement a customized SiteAuthenticator in which the startAuthentication method would forward requests to your new servlet.

Displaying Image Thumbnails

Browse and Search Results Page Thumbnails

Image thumbnails can be enabled on the Browse and Search Results pages by setting the appropriate configuration values. To enable the display of thumbnails the following items must be set in the dspace.cfg file:

webui.browse.thumbnail.show = true

If set to false or this configuration item is missing then thumbnails will not be shown.

The size of the browse/search thumbnails can also be configured to a smaller size than that generated by the mediafilter. To do this set the following configuration items:

webui.browse.thumbnail.maxheight = <maxheight in pixels>

webui.browse.thumbnail.maxwidth = <maxwidth in pixels>

If these configuration items are not set, thumbnail.maxheight and thumbnail.maxwidth are used. Setting these values greater than or equal to the size of the thumbnail generated by the mediafilter (i.e. thumbnail.maxheight and thumbnail.maxwidth) will have no effect.

Note:

• where the primary bitstream is HTML, no thumbnail is shown;
• where the primary bitstream has a thumbnail, its thumbnail is shown;
• where the primary bitstream is not set, the first thumbnail found by DSpace will be shown;
• where the user does not have read access to the thumbnail bitstream, no thumbnail is shown;
• currently, for a thumbnail to display, a JPEG thumbnail under the current implementation rules must exist (i.e. primary bitstream name with ".jpg" suffix).

Configuring Thumbnail Link Behaviour

The target of a thumbnail in the Browse and Search Results Page can be configured by setting the following configuration item:

webui.browse.thumbnail.linkbehaviour = <target page type>

Currently the values item and bitstream are allowed. If this configuration item is not set, or set incorrectly, the default is item.

Item Display Page Thumbnails

Thumbnails may also be enabled or disabled on the Item Display page by setting the following configuration item in dspace.cfg:

webui.item.thumbnail.show = true

If set to false or this configuration item is missing then thumbnails will not be shown.

Displaying Community and Collection Item Counts

To show the item count against communities and collections set the webui.strengths.show configuration item in the dspace.cfg file as follows:

webui.strengths.show = true

If this config item is missing or is set to any value other than true the item counts will not be shown

Internationalisation

The Java Standard Tag Library v1.0 is used to specify messages in the JSPs like this:

OLD:

<H1>Search Results</H1>

NEW:

<H1><fmt:message key="jsp.search.results.title" /></H1>

This message can now be changed using the config/Messages.properties file. (This must be done at build-time: Messages.properties is placed in the dspace.war Web application file.)

jsp.search.results.title = Search Results

Phrases may have parameters to be passed in, to make the job of translating easier, reduce the number of 'keys' and to allow translators to make the translated text flow more appropriately for the target language.

OLD:

<P>Results <%= r.getFirst() %> to <%= r.getLast() %> of <%= r.getTotal() %></P>

NEW:

<fmt:message key="jsp.search.results.text">
  <fmt:param><%= r.getFirst() %></fmt:param>
  <fmt:param><%= r.getLast() %></fmt:param>
  <fmt:param><%= r.getTotal() %></fmt:param>

</fmt:message>

(Note: JSTL 1.0 does not seem to allow JSP <%= %> expressions to be passed in as values of attribute in <fmt:param value=""/>)

The above would appear in the Messages_xx.properties file as:

jsp.search.results.text = Results {0}-{1} of {2}

Introducing number parameters that should be formatted according to the locale used makes no difference in the message key compared to atring parameters:

jsp.submit.show-uploaded-file.size-in-bytes = {0} bytes

In the JSP using this key can be used in the way belov:

<fmt:message key="jsp.submit.show-uploaded-file.size-in-bytes">
  <fmt:param><fmt:formatNumber><%= bitstream.getSize() %></fmt:formatNumber></fmt:param>

</fmt:message>

(Note: JSTL offers a way to include numbers in the message keys as jsp.foo.key = {0,number} bytes. Setting the parameter as <fmt:param value="${variable}" /> workes when variable is a single variable name and doesn't work when trying to use a method's return value instead: bitstream.getSize(). Passing the number as string (or using the <%= %> expression) also does not work.)

Multiple Messages.properties can be created for different languages. See ResourceBundle.getBundle. e.g. you can add German and Canadian French translations:

Messages_de.properties
Messages_fr_CA.properties

The end user's browser settings determine which language is used. Messages_en.properties (or the default server locale) will be used as a default if there's no language bundle for the end user's preferred language.

The dspace:layout tag has been updated to allow dictionary keys to be passed in for the titles. It now has two new parameters: titlekey and parenttitlekey. So where before you'd do:

<dspace:layout title="Here"
               parentlink="/mydspace"
               parenttitle="My DSpace">

You now do:

<dspace:layout titlekey="jsp.page.title"
               parentlink="/mydspace"
               parenttitlekey="jsp.mydspace">

And so the layout tag itself gets the relavent stuff out of the dictionary. title and parenttitle still work as before for backwards compatibility, and the odd spot where that's preferable.

Message Key Convention

When translating further pages, please follow the convention for naming message keys to avoid clashes.

For text in JSPs use the complete path + filename of the JSP, then a one-word name for the message. e.g. for the title of jsp/mydspace/main.jsp use:

jsp.mydspace.main.title

Some common words (e.g. "Help") can be brought out into keys starting jsp. for ease of translation, e.g.:

jsp.admin = Administer

Other common words/phrases are brought out into 'general' parameters if they relate to a set (directory) of JSPs, e.g.

jsp.tools.general.delete = Delete

Phrases that relate strongly to a topic (eg. MyDSpace) but used in many JSPs outside the particular directory are more convenient to be cross-referenced. For example one could use the key below in jsp/submit/saved.jsp to provide a link back to the user's MyDSpace:

(Cross-referencing of keys in general is not a good idea as it may make maintenance more difficult. But in some cases it has more advantages as the meaning is obvious.)

jsp.mydspace.general.goto-mydspace = Go to My DSpace

For text in servlet code, in custom JSP tags or wherever applicable use the fully qualified classname + a one-word name for the message. e.g.

org.dspace.app.webui.jsptag.ItemListTag.title = Title
org.dspace.app.webui.servlet.CommunityListServlet.

Which Languages are currently supported?

To view translations currently being developed, please refer to the i18n page of the DSpace Wiki.

On-line Help About File Formats

Because the file format support policy is determined by each individual institution, the on-line help on this subject is intentionally left blank. The help file will, however, retrieve a list of formats and the support levels associated with them in your database and display this information to the user. We highly recommend that you edit the "Format Support Policy" section of the file [dspace-source]/jsp/help/formats.jsp.