mirror of
https://github.com/DSpace/DSpace.git
synced 2025-10-14 21:43:11 +00:00
0bd461646d
git-svn-id: http://scm.dspace.org/svn/repo/dspace/trunk@5002 9c30dcfa-912a-0410-8fc2-9e0234be79fd
81 lines
26 KiB
HTML
81 lines
26 KiB
HTML
<html><head><META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter 10. DSpace System Documentation: Directories and Files</title><meta content="DocBook XSL Stylesheets V1.75.2" name="generator"><link rel="home" href="index.html" title="DSpace Manual"><link rel="up" href="index.html" title="DSpace Manual"><link rel="prev" href="ch09.html" title="Chapter 9. DSpace System Documentation: Storage Layer"><link rel="next" href="ch11.html" title="Chapter 11. DSpace System Documentation: Architecture"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF" marginwidth="5m"><div class="navheader"><table summary="Navigation header" width="100%"><tr><th align="center" colspan="3">Chapter 10. DSpace System Documentation: Directories and Files</th></tr><tr><td align="left" width="20%"><a accesskey="p" href="ch09.html">Prev</a> </td><th align="center" width="60%"> </th><td align="right" width="20%"> <a accesskey="n" href="ch11.html">Next</a></td></tr></table><hr></div><div class="chapter" title="Chapter 10. DSpace System Documentation: Directories and Files"><div class="titlepage"><div><div><h2 class="title"><a name="N16C17"></a>Chapter 10. <a name="docbook-directories.html"></a>DSpace System Documentation: Directories and Files</h2></div></div><div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="ch10.html#N16C1D">10.1. Overview</a></span></dt><dt><span class="section"><a href="ch10.html#N16C45">10.2. Source Directory Layout</a></span></dt><dt><span class="section"><a href="ch10.html#N16D57">10.3. Installed Directory Layout</a></span></dt><dt><span class="section"><a href="ch10.html#N16DAC">10.4. Contents of JSPUI Web Application</a></span></dt><dt><span class="section"><a href="ch10.html#N16DE8">10.5. Contents of XMLUI Web Application (aka Manakin)</a></span></dt><dt><span class="section"><a href="ch10.html#N16E5C">10.6. Log Files</a></span></dt><dd><dl><dt><span class="section"><a href="ch10.html#N16F40">10.6.1. log4j.properties File.</a></span></dt></dl></dd></dl></div><div class="section" title="10.1. Overview"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="N16C1D"></a>10.1. <a name="docbook-directories.html-overview"></a>Overview</h2></div></div><div></div></div><p>A complete DSpace installation consists of three separate directory trees:</p><div class="variablelist"><dl><dt><span class="term">The source directory:</span></dt><dd><p> 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 <code class="literal">[dspace-source]</code>.</p></dd><dt><span class="term">The install directory:</span></dt><dd><p> 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 <code class="literal">[dspace]</code>.</p></dd><dt><span class="term">The web deployment directory:</span></dt><dd><p> 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 <code class="literal">[tomcat]/webapps/dspace</code>.</p></dd></dl></div></div><div class="section" title="10.2. Source Directory Layout"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="N16C45"></a>10.2. <a name="docbook-directories.html-sourcedir"></a>Source Directory Layout</h2></div></div><div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
|
||
<code class="literal">[dspace-source]</code>
|
||
<div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p><code class="literal">dspace/</code> - Directory which contains all build and configuration information for DSpace </p><div class="itemizedlist"><ul class="itemizedlist" type="square"><li class="listitem"><p><code class="literal">CHANGES</code> - Detailed list of code changes between versions.</p></li><li class="listitem"><p><code class="literal">KNOWN_BUGS</code> - Known bugs in the current version.</p></li><li class="listitem"><p><code class="literal">LICENSE</code> - DSpace source code license.</p></li><li class="listitem"><p><code class="literal">README</code> - Obligatory basic information file.</p></li><li class="listitem"><p><code class="literal">bin/</code> - Some shell and Perl scripts for running DSpace command-line tasks.</p></li><li class="listitem"><p><code class="literal">config/</code> - Configuration files: </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="literal">controlled-vocabularies/</code> - Fixed, limited vocabularies used in metadata entry</p></li><li class="listitem"><p><code class="literal">crosswalks/</code> - Metadata crosswalks - property files or XSL stylesheets</p></li><li class="listitem"><p><code class="literal">dspace.cfg</code> - The Main DSpace configuration file (You will need to edit this).</p></li><li class="listitem"><p><code class="literal">dc2mods.cfg</code> - Mappings from Dublin Core metadata to <a class="ulink" href="http://www.loc.gov/standards/mods/" target="_top">MODS</a> for the METS export.</p></li><li class="listitem"><p><code class="literal">default.license</code> - The default license that users must grant when submitting items.</p></li><li class="listitem"><p><code class="literal">dstat.cfg</code> , <code class="literal">dstat.map</code> - Configuration for statistical reports.</p></li><li class="listitem"><p><code class="literal">input-forms.xml</code> - Submission UI metadata field configuration.</p></li><li class="listitem"><p><code class="literal">news-side.html</code> - Text of the front-page news in the sidebar, only used in JSPUI.</p></li><li class="listitem"><p><code class="literal">news-top.html</code> - Text of the front-page news in the top box, only used in teh JSPUI.</p></li><li class="listitem"><p><code class="literal">emails/</code> - Text and layout templates for emails sent out by the system.</p></li><li class="listitem"><p><code class="literal">registries/</code> - <span class="bold"><strong>Initial</strong></span> 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.</p></li></ul></div></li><li class="listitem"><p><code class="literal">docs/</code> - DSpace system documentation. The technical documentation for functionality, installation, configuration, etc.</p></li><li class="listitem"><p><code class="literal">etc/</code> -
|
||
This directory contains administrative files needed for the install process and by developers, mostly database initialization and upgrade scripts. Any <code class="literal">.xml</code> files in <code class="literal">etc/</code> are common to all supported database systems.</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="literal">postgres/</code> - Versions of the database schema and updater SQL scripts for PostgreSQL.</p></li><li class="listitem"><p><code class="literal">oracle/</code> - Versions of the database schema and updater SQL scripts for Oracle.</p></li></ul></div></li><li class="listitem"><p><code class="literal">modules/</code> - The Web UI modules "overlay" directory. DSpace uses Maven to automatically look here for any customizations you wish to make to DSpace Web interfaces. </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="literal">jspui</code> - Contains all customizations for the JSP User Interface. </p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p><code class="literal">src/main/resources/</code> - The overlay for JSPUI <span class="emphasis"><em>Resources.</em></span> This is the location to place any custom Messages.properties files. <span class="emphasis"><em>(Previously this file had been stored at: <code class="literal">[dspace-source]/config/language-packs/Messages.properties</code></em></span></p></li><li class="listitem"><p><code class="literal">src/main/webapp/</code> - The overlay for JSPUI Web Application. This is the location to place any custom JSPs to be used by DSpace.</p></li></ul></div></li><li class="listitem"><p><code class="literal">lni</code> - Contains all customizations for the Lightweight Network Interface.</p></li><li class="listitem"><p><code class="literal">oai</code> - Contains all customizations for the OAI-PMH Interface.</p></li><li class="listitem"><p><code class="literal">sword</code> - Contains all customizations for the SWORD (Simple Web-service Offering Repository Deposit) Interface.</p></li><li class="listitem"><p><code class="literal">xmlui</code> - Contains all customizations for the XML User Interface (aka Manakin). </p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p><code class="literal">src/main/webapp/</code> - The overlay for XMLUI Web Application. This is the location to place custom Themes or Configurations. </p><div class="itemizedlist"><ul class="itemizedlist" type="square"><li class="listitem"><p><code class="literal">i18n/</code> - The location to place a custom version of the XMLUI's messages.xml (You have to manually create this folder)</p></li><li class="listitem"><p><code class="literal">themes/</code> - The location to place custom Themes for the XMLUI (You have to manually create this folder).</p></li></ul></div></li></ul></div></li></ul></div></li><li class="listitem"><p><code class="literal">src/</code> - Maven configurations for DSpace System. This directory contains the Maven and Ant build files for DSpace.</p></li><li class="listitem"><p><code class="literal">target/</code> - (Only exists after building DSpace) This is the location Maven uses to build your DSpace installation package. </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="literal">dspace-[version].dir</code> - The location of the DSpace Installation Package (which can then be installed by running <code class="literal">ant update</code>)</p></li></ul></div></li></ul></div></li></ul></div>
|
||
</p></li></ul></div></div><div class="section" title="10.3. Installed Directory Layout"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="N16D57"></a>10.3. <a name="docbook-directories.html-installdir"></a>Installed Directory Layout</h2></div></div><div></div></div><p>Below is the basic layout of a DSpace installation using the default configuration. These paths can be configured if necessary.</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
|
||
<code class="literal">[dspace]</code>
|
||
<div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p><code class="literal">assetstore/</code> - asset store files</p></li><li class="listitem"><p><code class="literal">bin/</code> - shell and Perl scripts</p></li><li class="listitem"><p><code class="literal">config/</code> - configuration, with sub-directories as above</p></li><li class="listitem"><p><code class="literal">handle-server/</code> - Handles server files</p></li><li class="listitem"><p><code class="literal">history/</code> - stored history files (generally RDF/XML)</p></li><li class="listitem"><p><code class="literal">lib/</code> - JARs, including dspace.jar, containing the DSpace classes</p></li><li class="listitem"><p><code class="literal">log/</code> - Log files</p></li><li class="listitem"><p><code class="literal">reports/</code> - Reports generated by statistical report generator</p></li><li class="listitem"><p><code class="literal">search/</code> - Lucene search index files</p></li><li class="listitem"><p><code class="literal">upload/</code> - temporary directory used during file uploads etc.</p></li><li class="listitem"><p><code class="literal">webapps/</code> - location where DSpace installs all Web Applications</p></li></ul></div>
|
||
</p></li></ul></div></div><div class="section" title="10.4. Contents of JSPUI Web Application"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="N16DAC"></a>10.4. <a name="docbook-directories.html-webapp"></a>Contents of JSPUI Web Application</h2></div></div><div></div></div><p>DSpace's Ant build file creates a <code class="literal">dspace-jspui-webapp/</code> directory with the following structure:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> (top level dir) </p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p> The JSPs</p></li><li class="listitem"><p>
|
||
<code class="literal">WEB-INF/</code>
|
||
<div class="itemizedlist"><ul class="itemizedlist" type="square"><li class="listitem"><p><code class="literal">web.xml</code> - DSpace JSPUI Web Application configuration and Servlet mappings</p></li><li class="listitem"><p><code class="literal">dspace-tags.tld</code> - DSpace custom tag descriptor</p></li><li class="listitem"><p><code class="literal">fmt.tld</code> - JSTL message format tag descriptor, for internationalization</p></li><li class="listitem"><p><code class="literal">lib/</code> - All the third-party JARs and pre-compiled DSpace API JARs needed to run JSPUI</p></li><li class="listitem"><p><code class="literal">classes/</code> - Any additional necessary class files</p></li></ul></div>
|
||
</p></li></ul></div></li></ul></div></div><div class="section" title="10.5. Contents of XMLUI Web Application (aka Manakin)"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="N16DE8"></a>10.5. <a name="docbook-directories.html-webapp.1"></a>Contents of XMLUI Web Application (aka Manakin)</h2></div></div><div></div></div><p>DSpace's Ant build file creates a <code class="literal">dspace-xmlui-webapp/</code> directory with the following structure:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> (top level dir) </p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p><code class="literal">aspects/</code> - Contains overarching Aspect Generator config and Prototype DRI (Digital Repository Interface) document for Manakin.</p></li><li class="listitem"><p><code class="literal">i18n/</code> - Internationalization / Multilingual support. Contains the <code class="literal">messages.xml</code> English language pack by default.</p></li><li class="listitem"><p><code class="literal">themes/</code> - Contains all out-of-the-box Manakin themes </p><div class="itemizedlist"><ul class="itemizedlist" type="square"><li class="listitem"><p><code class="literal">Classic/</code> - The classic theme, which makes the XMLUI look like classic DSpace</p></li><li class="listitem"><p><code class="literal">dri2xhtml/</code> - The base theme, which converts XMLUI DRI (Digital Repository Interface) format into XHTML for display</p></li><li class="listitem"><p><code class="literal">Reference/</code> - The default reference theme for XMLUI</p></li><li class="listitem"><p><code class="literal">template/</code> - A theme template...useful as a starting point for your own custom theme(s)</p></li><li class="listitem"><p><code class="literal">dri2xhtml.xsl</code> - The DRI-to-XHTML XSL Stylesheet. Uses the above 'dri2xhtml' theme to generate XHTML</p></li><li class="listitem"><p><code class="literal">themes.xmap</code> - The Theme configuration file. It determines which theme(s) are used by XMLUI</p></li></ul></div></li><li class="listitem"><p>
|
||
<code class="literal">WEB-INF/</code>
|
||
<div class="itemizedlist"><ul class="itemizedlist" type="square"><li class="listitem"><p><code class="literal">lib/</code> - All the third-party JARs and pre-compiled DSpace JARs needed to run XMLUI</p></li><li class="listitem"><p><code class="literal">classes/</code> - Any additional necessary class files</p></li><li class="listitem"><p><code class="literal">cocoon.xconf</code> - XMLUI's Apache Cocoon configuration</p></li><li class="listitem"><p><code class="literal">logkit.xconf</code> - XMLUI's Apache Cocoon Logging configuration</p></li><li class="listitem"><p><code class="literal">web.xml</code> - XMLUI Web Application configuration and Servlet mappings</p></li></ul></div>
|
||
</p></li></ul></div></li></ul></div></div><div class="section" title="10.6. Log Files"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="N16E5C"></a>10.6. <a name="docbook-directories.html-logfiles"></a>Log Files</h2></div></div><div></div></div><p>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.</p><div class="table"><a name="N16E65"></a><p class="title"><b>Table 10.1. DSpace Log File Locations</b></p><div class="table-contents"><table summary="DSpace Log File Locations" border="1" width="100%"><colgroup><col><col></colgroup><tbody><tr><td>
|
||
<p>
|
||
<span class="bold"><strong>Log File</strong></span>
|
||
</p>
|
||
</td><td>
|
||
<p>
|
||
<span class="bold"><strong>What's In It</strong></span>
|
||
</p>
|
||
</td></tr><tr><td>
|
||
<p>
|
||
<code class="literal">[dspace]/log/dspace.log</code>
|
||
</p>
|
||
</td><td>
|
||
<p>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 <code class="literal">[dspace-source]/config/templates/log4j.properties</code> file and then running "<code class="literal">ant init_configs</code>".</p>
|
||
</td></tr><tr><td>
|
||
<p>
|
||
<code class="literal">[tomcat]/logs/catalina.out</code>
|
||
</p>
|
||
</td><td>
|
||
<p>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 (<code class="literal">dspace.jar</code>), it would be logged in <code class="literal">catalina.out</code>.</p>
|
||
</td></tr><tr><td>
|
||
<p>
|
||
<code class="literal">[tomcat]/logs/hostname_log.yyyy-mm-dd.txt</code>
|
||
</p>
|
||
</td><td>
|
||
<p>If you're running Tomcat stand-alone (without Apache), it logs some information and errors for specific Web applications to this log file. <code class="literal">hostname</code> will be your host name (e.g. <code class="literal">dspace.myu.edu</code>) and <code class="literal">yyyy-mm-dd</code> will be the date.</p>
|
||
</td></tr><tr><td>
|
||
<p>
|
||
<code class="literal">[tomcat]/logs/apache_log.yyyy-mm-dd.txt</code>
|
||
</p>
|
||
</td><td>
|
||
<p>If you're using Apache, Tomcat logs information about Web applications running through Apache (<code class="literal">mod_webapp</code>) in this log file (<code class="literal">yyyy-mm-dd</code> being the date.)</p>
|
||
</td></tr><tr><td>
|
||
<p>
|
||
<code class="literal">[apache]/error_log</code>
|
||
</p>
|
||
</td><td>
|
||
<p>Apache logs to this file. If there is a problem with getting <code class="literal">mod_webapp</code> working, this is a good place to look for clues. Apache also writes to several other log files, though <code class="literal">error_log</code> tends to contain the most useful information for tracking down problems.</p>
|
||
</td></tr><tr><td>
|
||
<p>
|
||
<code class="literal">[dspace]/log/handle-plug.log</code>
|
||
</p>
|
||
</td><td>
|
||
<p>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 <code class="literal">[dspace-source]/config/templates/log4j-handle-plugin.properties</code>.</p>
|
||
</td></tr><tr><td>
|
||
<p>
|
||
<code class="literal">[dspace]/log/handle-server.log</code>
|
||
</p>
|
||
</td><td>
|
||
<p>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.</p>
|
||
</td></tr><tr><td>
|
||
<p>
|
||
<code class="literal">[dspace]/handle-server/error.log</code>
|
||
</p>
|
||
</td><td>
|
||
<p>On the other hand, a problem with CNRI's Handle server code might be logged here.</p>
|
||
</td></tr><tr><td>
|
||
<p><code class="literal">PostgreSQL log</code></p>
|
||
</td><td>
|
||
<p>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 <code class="literal">dspace.log</code>.</p>
|
||
</td></tr></tbody></table></div></div><br class="table-break"><div class="section" title="10.6.1. log4j.properties File."><div class="titlepage"><div><div><h3 class="title"><a name="N16F40"></a>10.6.1. log4j.properties File.</h3></div></div><div></div></div><p>the file <code class="literal">[dspace]/config/log4j.properties</code> 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:</p><div class="table"><a name="N16F4A"></a><p class="title"><b>Table 10.2. log4j.properties Table</b></p><div class="table-contents"><table summary="log4j.properties Table" border="1" width="100%"><colgroup><col><col></colgroup><tbody><tr><td><pre class="screen">log4j.rootCategory=INFO,A
|
||
log4j.logger.org.dspace=INFO,A1</pre></td><td>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</td></tr><tr><td><code class="literal">log4j.appender.A1=org.dspace.app.util.DailyFileAppender</code></td><td>This is the name of the log file creation method used. The DailyFileAppender creates a new date-stamped file every day or month.</td></tr><tr><td><code class="literal">log4j.appender.A1.File=${log.dir}/dspace.log</code></td><td>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.</td></tr><tr><td><code class="literal">log4j.appender.A1.DatePattern=yyy-MM-DD</code></td><td>This defines the format for the date stamp that is appended to the log file names. If you wish to have log files created monthyl instead of daily, change this to <code class="literal">yyyy-MM</code></td></tr><tr><td><code class="literal">log4j.appender.A1.MaxLogs=0</code></td><td>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.</td></tr></tbody></table></div></div><br class="table-break"></div></div></div><HR><p class="copyright">Copyright <20> 2002-2010
|
||
<a class="ulink" href="http://www.duraspace.org/" target="_top">DuraSpace</a>
|
||
</p><div class="legalnotice" title="Legal Notice"><a name="N1001D"></a><p>
|
||
<a class="ulink" href="http://creativecommons.org/licenses/by/3.0/us/" target="_top">
|
||
<span class="inlinemediaobject"><img src="http://i.creativecommons.org/l/by/3.0/us/88x31.png"></span>
|
||
</a>
|
||
</p><p>Licensed under a Creative Commons Attribution 3.0 United States License</p></div><div class="navfooter"><hr><table summary="Navigation footer" width="100%"><tr><td align="left" width="40%"><a accesskey="p" href="ch09.html">Prev</a> </td><td align="center" width="20%"> </td><td align="right" width="40%"> <a accesskey="n" href="ch11.html">Next</a></td></tr><tr><td valign="top" align="left" width="40%">Chapter 9. DSpace System Documentation: Storage Layer </td><td align="center" width="20%"><a accesskey="h" href="index.html">Home</a></td><td valign="top" align="right" width="40%"> Chapter 11. DSpace System Documentation: Architecture</td></tr></table></div></body></html> |