This page addresses the most commonly-asked technical questions about DSpace. See also the User FAQ page for anwers to general questions about DSpace. |
Table of Contents
The most recent stable version of DSpace, recommended for production use, is available from SourceForge. For more information on the most recent release of the software see the Current Release Notes.
To see what's in store for the future, see Next Release Status and the DSpace RoadMap.
DSpace is freely available as open source software from SourceForge.
If you are a developer, DSpace is also available to be checked out using Git/GitHub: https://github.com/DSpace/DSpace See also Development with Git.
You're in the right place. First, you'll want to search this FAQ to see if your question has been asked/answered already. Next, try searching the DSpace System Documentation and the DSpace-Tech mailing list archives.
Still need help?
Post your questions to the DSpace-tech mailing list, where members of the DSpace community will offer their assistance.
And once you find the answer, if you think others will be asking the same question post them here in the Technical FAQ page.
Yes, the DSpace System Documentation includes a section on Installation. Read through this FAQ and also see Installation Guides.
If you run into any problems or have further questions, send an email to the DSpace-Tech mailing list for help.
If you think you've found a bug, we recommend taking the following steps.
Thanks for being willing to help locate and report bugs! An active community helps us make more stable, bug-free software.
Before putting in a new feature request, you should make sure that the feature would be useful to the broader DSpace community and isn't institutional specific. It's also worth mentioning that since the DSpace developers are all volunteers, you may want to work to locate an interested developer who can help you scope out and begin to develop this new feature.
If you've come up with a new feature idea, we recommend taking the following steps.
See the Troubleshoot an error page for hints on which log files to check for errors, and the recommended way of sending these to the DSpace-Tech Mailing List
## In Linux, run the following command then reproduce the internal error state ## use the pathname prefix appropriate to your DSpace installation tail -F /var/logs/dspace.log ## and you should see something of the kind 2009-05-18 12:52:45,935 WARN org.dspace.app.webui.servlet.DSpaceServlet @ name\ @place:session_id=F32DD4066DD475B8841A2A2204961B9A:ip_addr=1.2\ .3.4:database_error:org.postgresql.util.PSQLException: ERROR: duplicate key \ violates unique constraint "metadatafieldregistry_pkey" org.postgresql.util.PSQLException: ERROR: duplicate key violates unique constra\ int "metadatafieldregistry_pkey" at org.postgresql.core.v3.QueryExecutorImpl.receiveErrorResponse(QueryE\ xecutorImpl.java:1525) |
From the Documentation, see Storage Layer (which describes the basics for backing up your database and file storage). Also see AIP Backup and Restore, which describes how to backup your DSpace to a set of Archival Information Packages (AIPs).
Finally, there is a somewhat outdated summary at BackupRestore.
See Running DSpace on Standard Ports
See SecuringDspace,
Also ServletSecurity for more details.
See DSpaceOnWindows
A couple of things to try:
If you've upgraded to DSpace 1.2 from a prior version, ensure that your header JSP includes the following line:
<SCRIPT LANGUAGE="JavaScript" src="<%= request.getContextPath() %>/utils.js"></script> |
That needs to be in the <HEAD> element. It's in jsp/layout/header-default.jsp
but if you have a locally modified version, your modified copy might not have this line.
jsp/utils.js
to window.document.forms0
.dspace-admin/eperson-main.jsp
. If, for example, you placed a search box in your location bar, changing locbar="/dmirror/http/wiki.dspace.org/link"
to locbar="off"
in the dspace:layout tag in eperson-main should resolve the issue.Many people have two installs of DSpace: a test server and a production server. The problem is how to take data from the test server and integrate (move, append, migrate, etc.) it into the production server. The most common example is when you are ready to move a new collection from test into production. Note that this is a somewhat different problem than the need to move all data from a test server and completely overwrite any data on the production system, which may happen when first moving out of test and into production. RichardJones covers that scenario more completely here, along with a number of other DSpace-related topics.
The main problem in accomplishing this task easily is that some of the metadata will be duplicated if the export from your test server is imported directly and without modification into the production server. In particular, the following metadata elements will be affected:
Many people have run into trouble getting DSpace running on Redhat/Fedora Core Linux, specifically, encountering CLASSPATH errors and relating to libgcj
.
The easiest way to resolve this is to remove all the PM-based Java components, and install the original binary packages: Java SDK from Sun, and Ant and Tomcat from Apache.org.
To remove the PM Java stuff, do:
rpm \-e libgcj |
This will probably throw up a load of dependency errors. You'll need to remove the packages that depend on libgcj
too.
Another useful list from RichardJones of packages he had to remove from Fedora Core 2:
libgcj gcc-java-3.3.3-7 libgcj-devel-3.3.3-7 gettext-0.14.1-2.1 gcc34-java-3.4.0-1 ant-1.5.2-26 tomcat-4.1.27-13 |
Clive Gould has published a very useful blog explaining how to get DSpace working with a default install of CentOS 5.x, including Apache/Tomcat integration.
The Post Street Archives in Midland, Michigan with funding from the Herbert H. and Grace A. Dow Foundation worked with a team of students at Michigan Technological University to install DSpace for their digital archives. They produced http://www.poststreetarchives.org/DSpaceInstall.pdf this set of installation instructions for novice users on Fedora Core 4.
You also may wish to check Installation Guides for additional installation tips/suggestions relating to specific operating systems.
If filter-media appears to hang after it creates the thumbnails and indexes text content, you may consider running filter-media as root. For some reason, certain users report that filter-media
will hang after printing the following message:
Creating search index:
My personal experience shows that this happens when I run it as dspace, but not as root. Not sure yet why this happens, but this may be a quick fix until it is sorted out. Also, bear this potential "problem" in mind when setting up cron jobs for filter-media, index-all, and others.
Also note that running index-all as dspace does not hang, even though it does (apparently) the same thing.
If something doesn't seem to be working, you can often find out more by upping the logging level of DSpace. To do this:
dspace]
/config/log4j.properties.
Change the level by changing this line:
log4j.rootCategory=INFO, A1 |
to this:
log4j.rootCategory=DEBUG, A1 |
Now you'll find there's a lot more information in [dspace]
/log/dspace.log
. You can switch on and off logging for particular DSpace classes. For example, if you just want to know about SQL queries going to the database, you could leave the main level above as INFO, and instead add the following line (then restart Tomcat):
log4j.logger.org.dspace.storage.rdbms.DatabaseManager=DEBUG, A1 |
More information about DSpace log files is available in the DSpace System Documentation.
Adding a new Dublin Core field can be done from the Administrative User Interface of DSpace.
After you've added a new field, you can add it to the Search (Lucene) Index or Browse Index by following the directions in the "Configuration and Customization" chapter of the DSpace System Documentation.
In that chapter you'll also find hints/tips on customizing your User Interface display to show this new field.
Additional help can be found in the on this wiki.
The DSpace System Documentation includes a chapter titled "Customizing and Configuring Submission User Interface" which details how to make this and many other Submission UI customizations.
The DSpace System Documentation includes a section on "Configuring Lucene Search Indexes" in the chapter on "Configuration and Customization".
See the on this wiki for more help.
After setting up the DSpace database and properly setting up the application, most functionality appears normal. However, when adding content all the fields are null when it comes time to review a content submission. The Java errors thrown revolve around a null pointer exception.
See ModJk.
If you want to use an encoding other than UTF-8 you can edit the file src/org/dspace/storage/rdbms/DatabaseManager.java and modify the next lines
else if ((jdbctype == Types.CLOB && "oracle".equals(dbName)) || jdbctype == Types.VARCHAR) { // Support CLOBs in place of TEXT columns in Oracle row.setColumn(name, results.getString(i)); } /*else if (jdbctype == Types.VARCHAR) { try { byte[] bytes = results.getBytes(i); if (bytes != null) { String mystring = new String(results.getBytes(i), "UTF-8"); row.setColumn(name, mystring); } else { row.setColumn(name, results.getString(i)); } } catch (UnsupportedEncodingException e) { // do nothing, UTF-8 is built in! } }*/ |
Apache Cocoon, the DSpace component XMLUI is based on, keeps a cache of visited pages to speed up access to them. This can pose a problem usually during development of XMLUI themes, when you update XSL, but an older version of the page is served from cache instead of the current version being constructed. It's safe to clear the cache, the only impact it can have is on speed until the cache is repopulated.
In DSpace 1.8.0 and newer, there is a convenient link in XMLUI to clear the cache without restarting the servlet container:
Next to that link, you can also see how many pages are currently cached.
In DSpace versions up to 1.7.2, you have to clear the cache manually by shutting down Tomcat, deleting the cache directory and then restarting Tomcat:
${tomcat6.home}/bin/shutdown.sh |
cd ${tomcat6.home}/work/Catalina/{appropriate.domain.dir}/_/ |
rm -rf cache-dir |
Depending on your Tomcat version, whether you used a package and where you installed it, some common locations of the cache directory are:
/var/cache/tomcat5/work/Catalina/localhost/xmlui/cache-dir /var/lib/tomcat6/work/Catalina/localhost/_/cache-dir /opt/tomcat6/work/Catalina/localhost/xmlui/cache-dir /usr/local/tomcat6/work/Catalina/localhost/xmlui/cache-dir |
You have to remember that access restrictions are inherited from its parent collection only when items are submitted, not when access restrictions are modified. So the new items submitted to that collection will have the collection's restrictions you set, but existing items will keep their current permissions.
In other words: "When a new item gets archived in the repository, it inherits the default policies for an item, defined by the collection in which the item is archived. It's important to realize that these policies can altered for each item, bundle or bitstream, without altering other items or collection properties. Policies are really tied to items, bundles and bitstreams." source
So how would you do a mass-change of permissions?
This will remove the search box from the homepage body and keep the search box in the menu:
<xsl:template name="disable_front-page-search" match="dri:div[@id='aspect.discovery.SiteViewer.div.front-page-search']"> </xsl:template> |
These are the tables corresponding to individual browse indexes. Browse indexes are defined in dspace.cfg as webui.browse.index.1 through webui.browse.index.n and you can modify which metadata fields you want in the indexes, but you have to remember that after any such change, you need to re-create the indexes.
See ReIndexing Content (for Browse or Search) in the official documentation for your version of DSpace.
See also the relevant dspace.cfg section.
This happens when you skip a step in the instructions for Discovery#EnablingDiscovery. In particular, forgetting to set recent.submissions.count = 0
will mean that recent items continue to be rendered by the Browse aspect in addition to the Discovery aspect, resulting in duplication.
To fix this, set recent.submissions.count = 0
in [dspace]/config/dspace.cfg
and restart your servlet container. If needed, also clear the Cocoon cache: TechnicalFaq#TechnicalFaq-ClearingCocoon(XMLUI)cache
The Messages.properties file is used for translations both in DSpace core ([dspace]/lib/dspace-api-4.0-SNAPSHOT.jar) and in DSpace JSPUI ([dspace]/webapps/jspui/WEB-INF/lib/dspace-api-4.0-SNAPSHOT.jar). You usually want to update the JSPUI one:
From the related email thread:
The issue is related to the Access Rights Awareness feature introduced in Discovery and affect both the search and the browse system (when SolrBrowseDAO are used, optional in 3.x, by default in 4.0).
The issue here is that a single user is included in several groups - that means that the Solr query will include a filter to limit the results to only items that are visible by group1, group2, .... groupN.
Solutions:
in case of exceeding header size:
in case of tooManyClauses Exception:
http://example.com:8080/solr/statistics
) will result in an error (usually status code 403 Unauthorized).server=http://localhost:8080/solr/statistics
in [dspace]/config/modules/solr-statistics.cfg
.solr.url=http://localhost:8080/solr/oai
in [dspace]/config/modules/oai.cfg
andsearch.server=http://localhost:8080/solr/search
in [dspace]/config/modules/discovery.cfg
solr.server=http://localhost:8080/solr
in [dspace-source]/build.properties