Page History
...
- Download DSpace 5.0: Either download DSpace 5.0 from DSpace.org or check it out directly from the Github repository.
- NOTE: If you downloaded DSpace do not unpack it on top of your existing installation. Refer to Installation Instructions, Step 3 for unpacking directives.
- Merge any customizations (if needed). If you have made any local customizations to your DSpace installation they may need to be migrated over to the new DSpace.
- NOTE: If you are upgrading across many versions of DSpace at once (e.g. from 1.x.x to 5.x), you may find it easier to first upgrade DSpace, and then attempt to migrate over your various customizations. Because each major version of DSpace tends to add new configurations and features, older customizations may require more work to "migrate" to the latest version of DSpace.
- Customizations are typically housed in one of the following places:
- JSPUI modifications:
[dspace-source]/dspace/modules/jspui/src/main/webapp/
- XMLUI modifications:
[dspace-source]/dspace/modules/xmlui/src/main/webapp/
- Config modifications:
[dspace]/config
- JSPUI modifications:
Edit the build.properties file (if needed) (
[dspace-source]/build.properties
). Any settings changed in thisbuild.properties
file are automatically copied over to the finaldspace.cfg
file during the "Build DSpace" process (in the next step). For more information on the build.properties file, see "The build.properties Configuration Properties File" section of the Configuration Reference documentation.Build DSpace. Run the following commands to compile DSpace :
Code Block cd [dspace-source]/dspace/ mvn -U clean package
The above command will re-compile the DSpace source code and build its "installer". You will find the result in
[dspace-source]/dspace/target/dspace-installer
Info title Defaults to PostgreSQL settings Without any extra arguments, the DSpace installation package is initialized for PostgreSQL. If you use Oracle instead, you should build the DSpace installation package as follows:
mvn -Ddb.name=oracle -U clean package
Info title Enabling and building the DSpace 5 Mirage 2 theme Mirage 2 is a responsive theme for the XML User Interface, added as a new feature in DSpace 5. It has not yet replaced the Mirage 1 theme as the XMLUI default theme.
To enable Mirage 2, add the following to the
<themes>
section ofsrc/dspace/config/xmlui.xconf
, replacing the currently active theme:<theme name="Mirage 2" regex=".*" path="Mirage2/" />
It is important to do this before executing the maven build.
Mirage 2 is not yet activated in the default "mvn package" build. To include it as part of the build, run:
mvn -U clean package -Dmirage2.on=true
The speed of this specific step of the build can be increased by installing local copies of the specific dependencies required for building Mirage 2. The Mirage 2 developer documentation provides detailed instructions for these installations. After the installation of these dependencies, you can choose to run:
mvn -U clean package -Dmirage2.on=true -Dmirage2.deps.included=false
- Stop Tomcat (or servlet container). Take down your servlet container.
- For Tomcat, use the
$CATALINA_HOME/shutdown.sh
script. (Many Unix-based installations will have a startup/shutdown script in the/etc/init.d
or/etc/rc.d
directories.)
- For Tomcat, use the
Update DSpace Installation. Update the DSpace installation directory with the new code and libraries. Issue the following commands:
Code Block cd [dspace-source]/dspace/target/dspace-installer ant update
- Update your DSpace Configurations. You should review your configuration for new and changed configurations in DSpace 5.0.
- In the specific case of
dspace.cfg
it is recommended to start with a fresh copy of the file from the new version and copy your site-specific settings from the old file. Read the new file carefully to see if you need (or want) other alterations. - Please notice that as of DSpace 4, the default search and browse support has changed from the old Lucene/DBMS-based method to Discovery.
- In the specific case of
Decide which DSpace Web Applications you want to install. DSpace comes with a variety of web applications (in
[dspace]/webapps
), each of which provides a different "interface" to your DSpace. Which ones you install is up to you, but there are a few that we highly recommend (see below):"xmlui" = This is the XML-based User Interface, based on Apache Cocoon. It comes with a variety of out-of-the-box themes, including Mirage 1 (the default) and Mirage 2 (based on Bootstrap). Between the "xmlui" and "jspui", you likely only need to choose one.
"jspui" = This is the JSPUI-based User Interface, which is based on Bootstrap. Between the "xmlui" and "jspui", you likely only need to choose one.
"solr" (required) = This is Apache Solr web application, which is used by both the "xmlui" and "jspui" for search & browse functionality. It must be installed in support of either UI.
- "oai" = This is the DSpace OAI interface. It allows for Metadata and Bitstream (content-file) harvesting, supporting OAI-PMH (Protocol for Metadata Harvest) and OAI-ORE (Object Reuse and Exchange) protocols
- "rest" = This is the DSpace REST API
- "sword" = This is the DSpace SWORDv1 interface. More info on SWORD protocol and its usage.
- "swordv2" = This is the DSpace SWORDv2 interface. More info on SWORD protocol and its usage.
- "rdf" (new) = This is the DSpace RDF interface.
- "lni" (deprecated) = This is the DSpace Lightweight Networking Interface, supporting WebDAV / SOAP / RPC API. It is disabled by default as we recommend using REST or SWORD for most activities. In order to build it you must rebuild DSpace with the following flag:
mvn package -Pdspace-lni
Deploy DSpace Web Applications. If necessary, copy the web applications from your
[dspace]/webapps
directory to the subdirectory of your servlet container (e.g. Tomcat):Code Block cp -R [dspace]/webapps/* [tomcat]/webapps/
See the installation guide for full details.
- Upgrade your database (optional, but recommended). As of DSpace 5, the DSpace code will automatically upgrade your database (from any prior version of DSpace. By default, this database upgrade occurs automatically when you restart Tomcat (or your servlet container). However, if you have a large repository or are upgrading across multiple versions of DSpace at once, you may wish to manually perform the upgrade (as it could take some time, anywhere from 5-15 minutes for large sites).
First, you can optionally verify whether DSpace correctly detects the version of your DSpace database. It is very important that the DSpace version is detected correctly before you attempt the migration:
Code Block [dspace]/bin/dspace database info # Look for a line at the bottom that says something like: # "Your database looks to be compatible with DSpace version ___"
Then, you can upgrade your DSpace database to the latest version of DSpace. (NOTE: check the DSpace log,
[dspace]/log/dspace.log.[date]
, for any output from this command)Code Block [dspace]/bin/dspace database migrate
- More information on this new "database" command can be found in Database Utilities documentation.
- Restart Tomcat (servlet container). Now restart your servlet container (Tomcat/Jetty/Resin) and test out the upgrade.
- Upgrade of database: If you didn't manually upgrade your database in the previous step, then your database will be automatically upgraded to the latest version. This may take some time (seconds to minutes), depending on the size of your repository, etc. Check the DSpace log (
[dspace]/log/dspace.log.[date]
) for information on its status. - Reindexing of all content for search/browse: If your database was just upgraded (either manually or automatically), all the content in your DSpace will be automatically re-indexed for searching/browsing. As the process can take some time (minutes to hours, depending on the size of your repository), it is performed in the background; meanwhile, DSpace can be used as the index is gradually filled. But, keep in mind that not all content will be visible until the indexing process is completed. Again, check the DSpace log (
[dspace]/log/dspace.log.[date]
) for information on its status.
- Upgrade of database: If you didn't manually upgrade your database in the previous step, then your database will be automatically upgraded to the latest version. This may take some time (seconds to minutes), depending on the size of your repository, etc. Check the DSpace log (
Upgrade Solr Indexes. After upgrading DSpace, you should optimize your Solr indexes to ensure that they are in the current format. Solr can upgrade recent formats to its current one. Doing this whenever you upgrade DSpace should keep the index format current.
Upgrading from DSpace 1.6.x, 1.7.x or 1.8.x: In DSpace 1.x versions, we used and older version of Solr which is no longer compatible with the current version of Solr. Unfortunately, this involves a manual upgrade process, as there's no easy way to automate it.
If you are using an older version of DSpace, you will see errors similar to this one until you manually upgrade your index:
Code Block Caused by: org.apache.lucene.index.IndexFormatTooOldException: Format version is not supported (resource: segment _386q in resource ChecksumIndexInput(MMapIndexInput(path="/space/dspace/solr/statistics/data/index/segments_37m6"))): 2.x. This version of Lucene only supports indexes created with release 3.0 and later.
Manually upgrading your Solr index involves temporarily downloading an older version of Lucene (on which Solr is based), and calling its IndexUpgrader script, e.g.
Code Block # Download Lucene 3.5.0, which can upgrade older Solr/Lucene indexes wget "http://search.maven.org/remotecontent?filepath=org/apache/lucene/lucene-core/3.5.0/lucene-core-3.5.0.jar" -O lucene-core-3.5.0.jar # Actually upgrade the indexes, by loading the lucene-core-3.5.0.jar and calling IndexUpgrader java -cp lucene-core-3.5.0.jar org.apache.lucene.index.IndexUpgrader [dspace]/solr/statistics/data/index/ java -cp lucene-core-3.5.0.jar
DSpace provides optimization commands for all Solr indexes. Which ones you need to run depend on which features you are using in DSpace.
Code Block # Optimize Discovery Search & Browse (everyone should run this) [dspace]/bin/dspace index-discovery -o # Optimize Usage Statistics (based on Solr). Run this if you have Usage Statistics enabled in your UI. [dspace]/bin/dspace stat-util -o # Optimize OAI-PMH indexes (based on Solr). Run this if you use the "oai" webapp. [dspace]/bin/dspace oai import -o
IF for some reason the above commands fail, you should instead manually optimize your indexes with a command line tool such as
wget
:Code Block wget http://www.example.com/solr/<core>/update?optimize=true
Depending on your setup, some or all of the following cores may exist:
search
,statistics
,oai
,authority
. To see what solr cores exist in your set-up, look for the directories in[dspace]/solr
- each directory corresponds to a solr core.If you have been through sever DSpace upgrades and have never optimized, there is a chance that your indexes are in a format too old for the most recent Solr to convert:
Caused by:Code Block org.apache.lucene.index.
IndexUpgrader [dspace]/solr/search/data/index/
- At this point in time, your older indexes will now be compatible with Solr / Lucene 3.5. At this point they are readable by the latest version of Solr. However, you should still optimize each of these indexes using the commands detailed in the "Upgrading from DSpace 3.x or Above" step below.
Upgrading from DSpace 3.x or above: DSpace provides optimization commands for all Solr indexes. Which ones you need to run depend on which features you are using in DSpace.
Code Block # Optimize Discovery Search & Browse (everyone should run this) [dspace]/bin/dspace index-discovery -o # Optimize Usage Statistics (based on Solr). Run this if you have Usage Statistics enabled in your UI. [dspace]/bin/dspace stat-util -o # Optimize OAI-PMH indexes (based on Solr). Run this if you use the "oai" webapp. [dspace]/bin/dspace oai import -o
Check your cron / Task Scheduler jobs. In recent versions of DSpace, some of the scripts names have changed.
Check the Scheduled Tasks via Cron documentation for details. Especially pay attention to the Solr Index optimization commands, which ideally should be run regularly (as noted in the previous step).