Overview

A complete DSpace installation consists of three separate directory trees:

Source Directory Layout

Installed Directory Layout

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

Contents of JSPUI Web Application

DSpace's Ant build file creates a dspace-jspui-webapp/ directory with the following structure:

Contents of XMLUI Web Application (aka Manakin)

DSpace's Ant build file creates a dspace-xmlui-webapp/ directory with the following structure:

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.

Log File

What's In It

[dspace]/log/dspace.log.yyyy-mm-dd

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-source]/config/templates/log4j.properties file and then running "ant init_configs".

[dspace]/log/cocoon.log.yyyy-mm-dd

Apache Cocoon log file for the XMLUI. This is where the DSpace XMLUI logs all of its events and errors.

[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-source]/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.

log4j.properties File.

the file [dspace]/config/log4j.properties controls how and where log files are created. There are three sets of configurations in that file, called A1, A2, and A3. These are used to control the logs for DSpace, the checksum checker, and the XMLUI respectively. The important settings in this file are:

log4j.rootCategory=INFO,A
log4j.logger.org.dspace=INFO,A1

These lines control what level of logging takes place. Normally they should be set to INFO, but if you need to see more information in the logs, set them to DEBUG and restart your web server

log4j.appender.A1=org.dspace.app.util.DailyFileAppender

This is the name of the log file creation method used. The DailyFileAppender creates a new date-stamped file every day or month.

log4j.appender.A1.File=${log.dir}/dspace.log

This sets the filename and location of where the log file will be stored. It iwll have a date stamp appended to the file name.

log4j.appender.A1.DatePattern=yyy-MM-DD

This defines the format for the date stamp that is appended to the log file names. If you wish to have log files created monthly instead of daily, change this to yyyy-MM

log4j.appender.A1.MaxLogs=0

This defines how many log files will be created. You may wish to define a retention period for log files. If you set this to 365, logs older than a year will be deleted. By default this is set to 0 so that no logs are ever deleted. Ensure that you monitor the disk space used by the logs to make sure that you have enough space for them. It is often important to keep the log files for a long time in case you want to rebuild your statistics.