Chapter 10. DSpace System Documentation: Directories and Files  


Chapter 10. DSpace System Documentation: Directories and Files
Table of Contents 10.1. Overview 10.2. Source Directory Layout 10.3. Installed Directory Layout 10.4. Contents of JSPUI Web Application 10.5. Contents of XMLUI Web Application (aka Manakin) 10.6. Log Files 10.6.1. File.

10.1. 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 [ d s p a c e s o u r c e ] . 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 [ d s p a c e ] . 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 [ t o m c a t ] / w e b a p p s / d s p a c e .

10.2. Source Directory Layout
[ d s p a c e s o u r c e ]

d s t a t . c f g  ­ Mappings from Dublin Core metadata to MODS for the METS export. R E A D M E  ­ Obligatory basic information file. K N O W N _ B U G S  ­ Known bugs in the current version. d c 2 m o d s . configuration. only used in JSPUI. n e w s s i d e . l i c e n s e  ­ The default license that users must grant when submitting items. after which they are maintained in the database. x m l  ­ Submission UI metadata field configuration.d s p a c e /  ­ Directory which contains all build and configuration information for DSpace C H A N G E S  ­ Detailed list of code changes between versions. p o s t g r e s /  ­ Versions of the database schema and updater SQL scripts for PostgreSQL. installation. c o n f i g /  ­ Configuration files: c o n t r o l l e d v o c a b u l a r i e s /  ­ Fixed. b i n /  ­ Some shell and Perl scripts for running DSpace command­line tasks. c f g  ­ The Main DSpace configuration file (You will need to edit this). These are only used on initial system setup. Any . i n p u t f o r m s . d e f a u l t . only used in teh JSPUI. e m a i l s /  ­ Text and layout templates for emails sent out by the system. mostly database initialization and upgrade scripts. The technical documentation for functionality. m a p  ­ Configuration for statistical reports. d o c s /  ­ DSpace system documentation. n e w s t o p . r e g i s t r i e s /  ­ Initial contents of the bitstream format registry and Dublin Core element/qualifier registry. d s t a t . etc. x m l  files in e t c /  are common to all supported database systems. e t c /  ­ This directory contains administrative files needed for the install process and by developers. c f g  . h t m l  ­ Text of the front­page news in the sidebar. L I C E N S E  ­ DSpace source code license. h t m l  ­ Text of the front­page news in the top box. . limited vocabularies used in metadata entry c r o s s w a l k s /  ­ Metadata crosswalks ­ property files or XSL stylesheets d s p a c e .

m o d u l e s /  ­ The Web UI modules "overlay" directory. t a r g e t /  ­ (Only exists after building DSpace) This is the location Maven uses to build your DSpace installation package. s r c / m a i n / w e b a p p /  ­ The overlay for XMLUI Web Application. d i r  ­ The location of the DSpace Installation Package (which can then be installed by running a n tu p d a t e ) 10. This is the location to place any custom JSPs to be used by DSpace. d s p a c e [ v e r s i o n ] .3. i 1 8 n /  ­ The location to place a custom version of the XMLUI's messages. (Previously this file had been stored at: [ d s p a c e s o u r c e ] / c o n f i g / l a n g u a g e p a c k s / M e s s a g e s . l n i  ­ Contains all customizations for the Lightweight Network files. x m l u i  ­ Contains all customizations for the XML User Interface (aka Manakin). This is the location to place custom Themes or Configurations. s w o r d  ­ Contains all customizations for the SWORD (Simple Web­service Offering Repository Deposit) Interface.xml (You have to manually create this folder) t h e m e s /  ­ The location to place custom Themes for the XMLUI (You have to manually create this folder). j s p u i  ­ Contains all customizations for the JSP User Interface. o a i  ­ Contains all customizations for the OAI­PMH Interface. These paths can be configured if necessary. s r c / m a i n / r e s o u r c e s /  ­ The overlay for JSPUI Resources. Installed Directory Layout Below is the basic layout of a DSpace installation using the default configuration. p r o p e r t i e s s r c / m a i n / w e b a p p /  ­ The overlay for JSPUI Web Application. DSpace uses Maven to automatically look here for any customizations you wish to make to DSpace Web interfaces. This directory contains the Maven and Ant build files for DSpace.o r a c l e /  ­ Versions of the database schema and updater SQL scripts for Oracle. s r c /  ­ Maven configurations for DSpace System. This is the location to place any custom Messages. [ d s p a c e ] a s s e t s t o r e /  ­ asset store files .

 with sub­directories as above h a n d l e s e r v e r /  ­ Handles server files h i s t o r y /  ­ stored history files (generally RDF/XML) l i b /  ­ JARs. i 1 8 n /  ­ Internationalization / Multilingual support.4. t l d  ­ JSTL message format tag descriptor. w e b a p p s /  ­ location where DSpace installs all Web Applications 10. including dspace. containing the DSpace classes l o g /  ­ Log files r e p o r t s /  ­ Reports generated by statistical report generator s e a r c h /  ­ Lucene search index files u p l o a d /  ­ temporary directory used during file uploads etc. Contains the m e s s a g e s . t l d  ­ DSpace custom tag descriptor f m t .5. x m l  ­ DSpace JSPUI Web Application configuration and Servlet mappings d s p a c e t a g s .b i n /  ­ shell and Perl scripts c o n f i g /  ­ configuration.jar. Contents of JSPUI Web Application DSpace's Ant build file creates a d s p a c e j s p u i w e b a p p /  directory with the following structure: (top level dir) The JSPs W E B I N F / w e b . x m l  English . Contents of XMLUI Web Application (aka Manakin) DSpace's Ant build file creates a d s p a c e x m l u i w e b a p p /  directory with the following structure: (top level dir) a s p e c t s /  ­ Contains overarching Aspect Generator config and Prototype DRI (Digital Repository Interface) document for Manakin. for internationalization l i b /  ­ All the third­party JARs and pre­compiled DSpace API JARs needed to run JSPUI c l a s s e s /  ­ Any additional necessary class files 10.

 which makes the XMLUI look like classic DSpace d r i 2 x h t m l /  ­ The base theme. Below is a table listing the main log files used in a typical DSpace setup. The ordering of the list is roughly the recommended order for searching them for the details about a particular problem or error. problems can occur in a variety of places.useful as a starting point for your own custom theme(s) d r i 2 x h t m l . l o g then running "a n ti n i t _ c o n f i g s ". p r o p e r t i e s  file and [ d s p a c e ] / l o g / d s p a c e . which converts XMLUI DRI (Digital Repository Interface) format into XHTML for display R e f e r e n c e /  ­ The default reference theme for XMLUI t e m p l a t e /  ­ A theme template. This is where the DSpace code writes a simple log of events and errors that occur within the DSpace code. and might be different for your system depending on where you installed DSpace and the third­party tools.language pack by default.1. DSpace Log File Locations Log File What's In It Main DSpace log file. Table 10. It determines which theme(s) are used by XMLUI W E B I N F / l i b /  ­ All the third­party JARs and pre­compiled DSpace JARs needed to run XMLUI c l a s s e s /  ­ Any additional necessary class files c o c o o n .. . x c o n f  ­ XMLUI's Apache Cocoon configuration l o g k i t . t h e m e s /  ­ Contains all out­of­the­box Manakin themes C l a s s i c /  ­ The classic theme. x m l  ­ XMLUI Web Application configuration and Servlet mappings 10. Uses the above 'dri2xhtml' theme to generate XHTML t h e m e s .. x m a p  ­ The Theme configuration file. The locations given are defaults. You can control the verbosity of this by editing the [ d s p a c e s o u r c e ] / c o n f i g / t e m p l a t e s / l o g 4 j . x s l  ­ The DRI­to­XHTML XSL Stylesheet. x c o n f  ­ XMLUI's Apache Cocoon Logging configuration w e b . Log Files The first source of potential confusion is the log files. Since DSpace uses a number of third­party tools.6.

 a problem with CNRI's Handle server code might be logged here. this is where it may be logged. On the other hand. d s p a c e . the file [ d s p a c e ] / c o n f i g / l o g 4 j . if Tomcat can't find the DSpace code (d s p a c e . Many errors that occur within the Tomcat code are logged here.) Apache logs to this file. t x t applications to this log file. You can control the verbosity of this by editing [ d s p a c e s o u r c e ] / c o n f i g / t e m p l a t e s / l o g 4 j h a n d l e p l u g i n . Tomcat logs information about Web applications running through Apache (m o d _ w e b a p p ) in this log file (y y y y m m d d  being the date. and these problems will be logged in d s p a c e . p r o p e r t i e s  controls how and where log files are created. t x t If you're using Apache. o u t . and A3. The Handle server runs as a separate process from the DSpace Web UI (which runs under Tomcat's JVM). y y y y . and the XMLUI respectively. l o g [ d s p a c e ] / l o g / h a n d l e s e r v e r . y y y y m m d d . The important settings in this file are: Table 10. These are used to control the logs for DSpace. [ d s p a c e ] / h a n d l e s e r v e r / e r r o r . l o g . it [ t o m c a t ] / l o g s / h o s t n a m e _ l o g . this is a good place to look for clues. called A1. PostgreSQL also writes a log file. [ t o m c a t ] / l o g s / a p a c h e _ l o g . p r o p e r t i e s .g. though e r r o r _ l o g  tends to contain the most useful information for tracking down problems. you probably had to specify it yourself at some point during installation. Apache also writes to several other log files. h o s t n a m e  will be your host name (e. j a r ).6. For example. l o g This is the log file for CNRI's Handle server code. This one doesn't seem to have a default location. A2. l o g P o s t g r e S Q Ll o g Table . e d u ) and y y y y m m d d  will be the date. o u t This is where Tomcat's standard output is written. the DSpace code running in the Handle server's JVM must use a separate log file. before DSpace's plug­in is invoked. m y u .1. you're more likely to encounter problems with connecting via File.[ t o m c a t ] / l o g s / c a t a l i n a . If there is a problem with getting m o d _ w e b a p p  working. In general.logs some information and errors for specific Web m m d d . There are three sets of configurations in that file. Due to a limitation of log4j's 'rolling file appenders'. [ a p a c h e ] / e r r o r _ l o g [ d s p a c e ] / l o g / h a n d l e p l u g . If you're running Tomcat stand­alone (without Apache). log4j. it would be logged in c a t a l i n a . If a problem occurs within the Handle server code. The DSpace code that is run as part of a Handle resolution request writes log information to this file. the checksum checker. log4j. this log file rarely contains pertinent information­­PostgreSQL is pretty stable.

l o g g e r . change this to y y y y M M l o g 4 j . This defines the format for the date stamp that is appended to the log file names. If you set this to 365. but if you need to see more information in the logs. Normally they should be set to INFO. It iwll have a date stamp appended to the file name.l o g 4 j . d s p a c e . logs older than a year will be deleted. The l o g 4 j . D a t e P a t t e r n = y y y M M D D l o g 4 j . set them to dEBUG and restart your web server This is the name of the log file creation method used. o r g . It is often important to keep the log files for a long time in case you want to rebuild your statistics. d i r } / d s p a c e . A l o g 4 j . a p p e n d e r . F i l e = $ { l o g . d s p a c e = I N F O . A 1 = o r g . Ensure that you monitor the disk space used by the logs to make sure that you have enough space for them. D a i l y F i l e A p p e n d e r DailyFileAppender creates a new date­stamped file every day or month. A 1 . a p p . A 1 These lines control what level of logging takes place. A 1 . a p p e n d e r . a p p e n d e r . u t i l . M a x L o g s = 0 This defines how many log files will be created. A 1 . a p p e n d e r . Copyright © 2002­2010 DuraSpace Licensed under a Creative Commons Attribution 3. r o o t C a t e g o r y = I N F O . By default this is set to 0 so that no logs are ever deleted. If you wish to have log files created monthyl instead of daily.0 United States License Prev     Next . You may wish to define a retention period for log files. l o g 4 j . l o g This sets the filename and location of where the log file will be stored.

Chapter 9. DSpace System Documentation: Architecture . DSpace System Documentation: Storage Layer  Home  Chapter 11.