DSpace System Documentation: Directories and Files

Overview

A complete DSpace installation consists of three separate directory trees:

The source directory:

This is where (surprise!) the source code lives. Note that the config files here are used only during the initial install process. After the install, config files should be changed in the install directory. It is referred to in this document as [dspace-source].

The install directory:

This directory is populated during the install process and also by DSpace as it runs. It contains config files, command-line tools (and the libraries necessary to run them), and usually--although not necessarily--the contents of the DSpace archive (depending on how DSpace is configured). After the initial build and install, changes to config files should be made in this directory. It is referred to in this document as [dspace].

The web deployment directory:

This directory is generated by the web server the first time it finds a dspace.war file in its webapps directory. It contains the unpacked contents of dspace.war, i.e. the JSPs and java classes and libraries necessary to run DSpace. Files in this directory should never be edited directly; if you wish to modify your DSpace installation, you should edit files in the source directory and then rebuild. The contents of this directory aren't listed here since its creation is completely automatic. It is usually referred to in this document as [tomcat]/webapps/dspace.

Source Directory Layout

[dspace-source]
- build.xml - build file for Ant
- CHANGES - Detailed list of code changes between versions
- KNOWN_BUGS - Known bugs in the current version
- LICENSE - DSpace source code license
- README - Obligatory basic information file
- bin/ - Some shell and Perl scripts for running DSpace command-line tasks
- config/ - configuration files
  - dspace.cfg - main DSpace configuration file
  - dc2mods.cfg - Mappings from Dublin Core metadata to MODS for the METS export
  - default.license - default license that users must grant when submitting items
  - dstat.cfg, dspace.map - statistical report configuration
  - input-forms.xml - Submission UI metadata field configuration
  - mediafilter.cfg - Media Filter configuration
  - news-side.html - Text of the front-page news in the sidebar
  - news-top.html - Text of the front-page news in the top box
  - emails/ - Texts of emails sent out by the system
  - language-packs/ - contains "dictionary files" -- Java properties files that contain user interface text in different languages
  - registries/ - initial contents of the bitstream format registry and Dublin Core element/qualifier registry. These are only used on initial system setup, after which they are maintained in the database.
  - templates/ - configuration files for libraries and external applications (e.g. Apache, Tomcat) are kept and edited here. They can refer to properties in the main DSpace configuration - have a look at a couple. When they're updated, a command line tool fills out these files with appropriate values from dspace.cfg, and copies them to their appropriate location (hence "templates".)
- etc/ - miscelleanous stuff need to install DSpace that isn't really to do with system configuration - e.g. the PostgreSQL database schema, and a couple of configuration files that are used during the build process but not by the live system. Also contains the deployment descriptors (web.xml files) for the Web UI and OAI-PMH support .war files.
  - oracle/ - versions of the database schema and updater SQL scripts for Oracle
- jsp/ - The Web UI JSPs. As much as possible, these are simply HTML with little bits of Java - the business code resides in the servlets
- lib/ - Library JARs used by the system
  - README - Lists the packages third-party libraries (JARs) and their use
  - licenses - Contains the licenses associated with the JARs
- src/ - DSpace system source code. For details on how this is laid out, see the overview page of the Javadoc.

Installed Directory Layout

Below is the basic layout of a DSpace installation using the default configuration. These paths can be configured if necessary.

[dspace]
- assetstore/ - asset store files
- bin/ - shell and Perl scripts
- config/ - configuration, with sub-directories as above
- handle-server/ - Handles server files
- history/ - stored history files (generally RDF/XML)
- lib/ - JARs, including dspace.jar, containing the DSpace classes
- log/ - Log files
- reports/ - Reports generated by statistical report generator
- search/ - Lucene search index files
- upload/ - temporary directory used during file uploads etc.

Contents of Web Application

DSpace's Ant build file creates a .war file with the following structure:

(top level dir)
- The JSPs
- WEB-INF/
  - web.xml - Created from [dspace-source]/etc/dspace-web.xml, appropriate filled out with configuration parameters (e.g. location of DSpace installation directory
  - dspace-tags.tld - DSpace custom tag descriptor
  - fmt.tld - JSTL message format tag descriptor, for internationalization
  - lib/ - All the third-party JARs needed to run DSpace
  - classes/ - The DSpace class files, plus all of the Messages_xx.properties files. The latter are placed here so they are in the CLASSPATH and thus can be picked up as resource bundles.

Log Files

The first source of potential confusion is the log files. Since DSpace uses a number of third-party tools, problems can occur in a variety of places. Below is a table listing the main log files used in a typical DSpace setup. The locations given are defaults, and might be different for your system depending on where you installed DSpace and the third-party tools. The ordering of the list is roughly the recommended order for searching them for the details about a particular problem or error.

DSpace Log File Locations
Log File	What's In It
`[dspace]/log/dspace.log`	Main DSpace log file. This is where the DSpace code writes a simple log of events and errors that occur within the DSpace code. You can control the verbosity of this by editing the `[dspace]/config/templates/log4j.properties` file and then running `[dspace]/bin/install-configs`.
`[tomcat]/logs/catalina.out`	This is where Tomcat's standard output is written. Many errors that occur within the Tomcat code are logged here. For example, if Tomcat can't find the DSpace code (`dspace.jar`), it would be logged in `catalina.out`.
`[tomcat]/logs/hostname_log.yyyy-mm-dd.txt`	If you're running Tomcat stand-alone (without Apache), it logs some information and errors for specific Web applications to this log file. `hostname` will be your host name (e.g. `dspace.myu.edu`) and `yyyy-mm-dd` will be the date.
`[tomcat]/logs/apache_log.yyyy-mm-dd.txt`	If you're using Apache, Tomcat logs information about Web applications running through Apache (`mod_webapp`) in this log file (`yyyy-mm-dd` being the date.)
`[apache]/error_log`	Apache logs to this file. If there is a problem with getting `mod_webapp` working, this is a good place to look for clues. Apache also writes to several other log files, though `error_log` tends to contain the most useful information for tracking down problems.
`[dspace]/log/handle-plug.log`	The Handle server runs as a separate process from the DSpace Web UI (which runs under Tomcat's JVM). Due to a limitation of log4j's 'rolling file appenders', the DSpace code running in the Handle server's JVM must use a separate log file. The DSpace code that is run as part of a Handle resolution request writes log information to this file. You can control the verbosity of this by editing `[dspace]/config/templates/log4j-handle-plugin.properties`.
`[dspace]/log/handle-server.log`	This is the log file for CNRI's Handle server code. If a problem occurs within the Handle server code, before DSpace's plug-in is invoked, this is where it may be logged.
`[dspace]/handle-server/error.log`	On the other hand, a problem with CNRI's Handle server code might be logged here.
PostgreSQL log	PostgreSQL also writes a log file. This one doesn't seem to have a default location, you probably had to specify it yourself at some point during installation. In general, this log file rarely contains pertinent information--PostgreSQL is pretty stable, you're more likely to encounter problems with connecting via JDBC, and these problems will be logged in `dspace.log`.