Page History
Info |
---|
In the notes below |
...
Note | ||
---|---|---|
| ||
In DSpace 13.8.0 , there have been a few significant changes to how you upgrade and configure DSpace. Notably:
|
Backup your DSpace
Before you start your upgrade, it is strongly recommended that you create a backup of your DSpace instance. Backups are easy to recover from; a botched install/upgrade is very difficult if not impossible to recover from. The DSpace specific things to backup are: configs, source code modifications, database, and assetstore. On your server that runs DSpace, you might additionally consider checking on your cron/scheduled tasks, servlet container, and database.
...
Database: Make a snapshot/dump of the database. For the PostgreSQL database use Postgres' pg_dump command. For example:
Code Block pg_dump -U [database-user] -f [backup-file-location] [database-name]
- Assetstore: Backup the directory (
[dspace]/assetstore
by default, and any other assetstores configured in the[dspace]/config/dspace.cfg
"assetstore.dir" and "assetstore.dir.#" settings) - Configuration: Backup the entire directory content of
[dspace]/config
. - Customizations: If you have custom code, such as themes, modifications, or custom scripts, you will want to back them up to a safe location.
Upgrade Steps
- Download DSpace 1.8.23.0: Either download DSpace 13.8.2 0 from DSpace.org or check it out directly from the SVN code Github repository. 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 you have made any local customizations to your DSpace installation they will need to be migrated over to the new 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 (
[dspace-source]/build.properties
). This new configuration file allows for an easier way to quickly configure your primary DSpace settings before building DSpace. It provides a subset of the most important configurations you may wish to make for your DSpace installation. 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 documentation. Build DSpace. Run the following commands to compile DSpace:
No Formatcode cd [dspace-source]/dspace/ mvn -U clean package
You will find the result in
[dspace-source]/dspace/target/dspace-[version]-build.dir
. Inside this directory is the compiled binary distribution of DSpace. Before rebuilding DSpace ('package'), the above command will clean out any previously compiled code ('clean') and ensure that your local DSpace JAR files are updated from the remote maven repository.- Stop Tomcat. 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.) - Update DSpace.
Update the DSpace installed directory with the new code and libraries. Issue the following commands:
Code Block cd [dspace-source]/dspace/target/dspace-[version]-build.dir ant -Dconfig=update
- Please run one of the following scripts to update your database:-
- PostgreSQL:
[dspace-source]/dspace/etc/postgres/database_schema_18-3.sql
- Oracle:
[dspace-source]/dspace/etc/oracle/database_schema_18-3.sql
- PostgreSQL:
- Update your DSpace Configurations. As necessary, you may wish to review the settings in
[dspace]/config/dspace.cfg
updateNote title Changes to the behavior of the 'ant update' script The
ant update
script has changed slightly as of DSpace 1.8. It now defaults to replacing your existing configuration files (after backing them up first). See the Changes to the DSpace 1.8 Upgrade / Configuration Process note at the top of this page for more details. - No database changes have been made in either 1.8.1 or 1.8.2. So there is no need to update your existing 1.8 database.
- Update your DSpace Configurations.
- There are no new configurations for the 1.8.1 or 1.8.2 releases. Your existing 1.8 configuration files should work fine
- and all configurations under
[dspace]/config/modules/
. This configuration settings can also be modified at any time in the future. You'd just need to restart Tomcat for any settings to take effect. Refresh Browse and Search Indexes. To do this, run the following command from your DSpace install directory (as the dspace user):
Code Block [dspace]/bin/dspace index-init
Refresh Discovery: If you are using Discovery (Solr) for search/browse, you will also need to refresh Discovery indexes by running the following command:
Code Block [dspace]/bin/dspace update-discovery-index -f
Update OAI-PMH indexes. DSpace 3.0 comes with a brand new OAI 2.0 Server which uses a Solr backend by default. As such, it needs to have its indexes updated on a regular basis. To update the OAI 2.0 indexes, you should run the following command:
Code Block [dspace]/bin/dspace oai import
Note title Enable an OAI-PMH index cron job This same '
dspace oai import
' command should also be run on a regular basis (e.g. via cron) to keep the OAI 2.0 indexes in sync. For more information, see the Scheduled Tasks section of the OAI 2.0 documentation.Info title Using OAI-PMH but not SOLR? If you are using OAI-PMH, but do not yet have the Solr webapp (
[dspace]/webapps/solr/
) installed, you will need to:(1) EITHER Modify the default OAI 2.0 config file (
[dspace]/config/modules/oai.cfg
) to use a database backend. See: OAI 2.0 Server#UsingDatabase(2) OR install/enable Tomcat to use the DSpace Solr webapp (
[dspace]/webapps/solr/
), and optionally configure the OAI settings in[dspace]/config/modules/oai.cfg
Change LDAPHierarchicalAuthentication to LDAPAuthentication. If you were using the LDAPHierarchicalAuthentication method in DSpace 1.8.x, you need to change your authentication plugin to LDAPAuthentication. The functionality from LDAPHierarchicalAuthentication is now part of LDAPAuthentication. This change should be made in
[dspace]/config/modules/authentication.cfg
in theplugin.sequence.org.dspace.authenticate.AuthenticationMethod
property. LDAP configuration in[dspace]/config/modules/authentication-ldap.cfg
remains the same, so you won't need to change anything. The only case (which should apply to a minority of users) when you do need to update your configuration is if you were using anonymous search (i.e. you were using LDAPHierarchicalAuthentication, but you didn't havesearch.user
andsearch.password
set); if that applies to you, edit[dspace]/config/modules/authentication-ldap.cfg
and set:Code Block search.anonymous = true
Refresh Browse and Search Indexes. Though there are not any database changes, it is a good policy to rebuild your search and browse indexes when upgrading to a new release. To do this, run the following command from your DSpace install directory (as the dspace user):
[dspace]/bin/dspace index-initCode Block A new feature in 3.0 is that you can now put users into DSpace groups based on a part of their DN in LDAP. See the new
login.groupmap.*
options in Authentication Plugins#ConfiguringLDAPAuthentication.
Deploy Web Applications. If necessary, copy the web applications files from your
[dspace]/webapps
directory to the subdirectory of your servlet container (e.g. tomcatTomcat):Code Block cp -R [dspace]/webapps/* [tomcat]/webapps/
See the installation guide for full details.
- Restart servlet container. Now restart your Tomcat/Jetty/Resin server program and test out the upgrade.