5. If you're using Tomcat 4.1.14 or higher, you may have to configure it to allow symbolic linking. For this, Add the following in server.xml inside the main "<Host>" section (so before the main "</Host>" tag):

6. Start Tomcat:

If you now go to https://your.dspace.server:8443/ you should see the DSpace you just installed. Replacing "your.dspace.server" with the hostname of your dspace server. This would be "localhost" in our example.

Creating an administrator account

To be able to go into the admin section (following earlier conventions, that would be https://your.dspace.server:8443/admin) you'll need to create an admin user from the shell. To do this, go to the dspace directory, and execute:

This will ask you for an email address, name and password, and set up the administrator.

Configuration and Customization

There are a number of ways to customize your DSpace installation. The most straightforward
is to edit the files in

(if you installed dspace in

, which is the default).

You can also edit the .jsp files (Java Server Page), and replace both the static HTML and the code in them. You can go even further and edit the sourcecode itself, or add more code to the system. However. All these methods are likely to produce a DSpace system which is very different from the main DSpace project, and is likely to break when you upgrade to the next DSpace version.

The dspace.cfg 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:

For more information, see the ConfigurationKeyIndex page.

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').

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.

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.

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.

The JSPs are stored in /dspace/jsp. Place your edited version of a JSP in the /dspace/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/jsp. For example:
DSpace default Locally-modified version
/dspace/jsp/community-list.jsp /dspace/jsp/local/community-list.jsp
/dspace/jsp/mydspace/main.jsp /dspace/jsp/local/mydspace/main.jsp

Heavy use is made of a style sheet, in /dspace/jsp/styles.css.jsp. If you make edits, call the local version /dspace/jsp/local/styles.css.jsp, and it will be used automatically in preference to the default, as described above. Be sure to remove the localVersion code to avoid a loop!.

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/jsp/layout/header-.jsp and /dspace/jsp/layout/footer-.jsp. You can provide modified versions of these (in /dspace/jsp/local/layout, or define more styles and apply them to pages by using the "style" attribute of the dspace:layout tag.

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.

3. 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 we use here 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.