Upgrading CollectionSpace

Owned by Adaptavist ScriptRunner for Confluence Cloud
Oct 28, 2020
5 min read

Prerequisites

Before upgrading your CollectionSpace server, make sure you have a viable backup of your installation that can be restored if any problems occur. A whole-system backup or VM snapshot is preferred, but at a minimum, the following should be backed up:

  • Databases - Use pg_dump to create archives of all postgres databases, and store the archives in a safe location.
  • Source code - Back up the CollectionSpace source code directories on your server. These directories are named services and application. If you used the automated installer, they can be found in the home directory of the cspace user, inside the collectionspace-source directory. These directories need to be backed up because you may have made configuration changes there – for example, to create tenants.
  • Tomcat - Back up the tomcat directory on your server. Tomcat is typically located at /usr/local/share/apache-tomcat-{version}. Substitute {version} with the number that exists on your server. This will vary with the CollectionSpace version – for example, 7.0.64 for CollectionSpace 5.1.

Upgrading from CollectionSpace 5.1

Install Tomcat 8

CollectionSpace 5.2 requires Tomcat 8, instead of Tomcat 7.

As a user with superuser privileges, go to the directory where Tomcat is installed – typically, /usr/local/share.

cd /usr/local/share

A pre-configured installation of Tomcat 8 is included in the CollectionSpace distribution package. Download the tarball:

sudo wget https://s3-us-west-2.amazonaws.com/cs-public-shared-files/releases/5.2/cspace-server-5.2.tar.gz

Unpack the tarball:

sudo tar -xzvof cspace-server-5.2.tar.gz

This will create a directory named apache-tomcat-8.5.40.

Change the files to be owned by the user you use to run CollectionSpace – typically, the cspace user:

sudo chown -R cspace:cspace apache-tomcat-8.5.40

Remove the tarball:

sudo rm cspace-server-5.2.tar.gz

Update Environment Variables

Change to the user you use to build and deploy CollectionSpace – typically, the cspace user.

sudo su - cspace

Edit the file in which environment variables are set for the build – typically, .bashrc in the home directory of the cspace user.

vim ~/.bashrc

In that file, find the lines where the CATALINA_HOME, CATALINA_PID, and CSPACE_JEESERVER_HOME variables are set. The values will contain the path to the old Tomcat 7 directory. Change them to use path of the new Tomcat 8 directory. The changed lines should now look like:

export CATALINA_HOME='/usr/local/share/apache-tomcat-8.5.40'
export CATALINA_PID='/usr/local/share/apache-tomcat-8.5.40/bin/tomcat.pid'
export CSPACE_JEESERVER_HOME='/usr/local/share/apache-tomcat-8.5.40'

Source the file to update the environment variables:

source ~/.bashrc

Upgrade Source Code

Continue to perform the following steps as the user you use to build and deploy CollectionSpace – typically, the cspace user.

CollectionSpace source code is normally located in the home directory of the cspace user, under the collectionspace-source directory.

If you created a tenant on your system using the clone-tenant tool, you will have edited the tenant.properties files in the services and application source code directories. These changes will prevent some the next steps form working. Usually, there's no need to retain the changed tenant.properties files after the tenant has been created, so you can remove your changes:

cd ~/collectionspace-source
cd services
git checkout tenant.properties
cd ../application
git checkout tenant.properties

Upgrade the source code to 5.2:

cd ~/collectionspace-source
cd services
git fetch
git checkout v5.2-branch
cd ../application
git fetch
git checkout v5.2-branch

Upgrade Tenant Back End (Services) Configuration

If you created a tenant in 5.1, there will be some back end configuration for the tenant in the application source code directory, in the directory named tomcat-main/src/main/resources/tenants/{tenant_short_name}, where {tenant_short_name} is the short name of your tenant. There will also be a directory containing configuration for the tenant that you used as a template to create your tenant, at tomcat-main/src/main/resources/tenants/{template_short_name}. Copy all of the files from the template tenant directory to your tenant directory, except for settings.xml. When copying, replace the template tenant's short name with your tenant's short name in each file name. For example, if your tenant's short name is mytenant, and it was created from the anthro tenant:

cd ~/collectionspace-source/application/tomcat-main/src/main/resources/tenants
ls anthro
> anthro-authority-concept.xml          anthro-collectionobject.xml       settings.xml
> anthro-authority-person-termList.xml  domain-instance-vocabularies.xml
cp anthro/anthro-authority-concept.xml mytenant/mytenant-authority-concept.xml
cp anthro/anthro-authority-person-termList.xml mytenant/mytenant-authority-person-termList.xml
cp anthro/anthro-collectionobject.xml mytenant/mytenant-collectionobject.xml
cp anthro/domain-instance-vocabularies.xml mytenant

There is additional configuration for your tenant in the file tomcat-main/src/main/resources/{tenant_short_name}-tenant.xml. This file was based on the corresponding file for the tenant you used as a template. That file is named tomcat-main/src/main/resources/{template_short_name}-tenant.xml. You will need to check if the configuration for the template tenant has changed between 5.1 and 5.2. If so, make the same changes to your tenant's configuration file. For example, if your tenant is based on the anthro tenant, use git to check for changes to tomcat-main/src/main/resources/anthro-tenant.xml:

cd ~/collectionspace-source/application
git diff -w v5.1 tomcat-main/src/main/resources/anthro-tenant.xml
> diff --git a/tomcat-main/src/main/resources/anthro-tenant.xml b/tomcat-main/src/main/resources/anthro-tenant.xml
> index 89a8a955..3de573ad 100644
> --- a/tomcat-main/src/main/resources/anthro-tenant.xml
> +++ b/tomcat-main/src/main/resources/anthro-tenant.xml
> @@ -18,6 +18,7 @@
>                        <include src="base-procedure-blobs.xml" />
>                        <include src="base-procedure-claim.xml,extensions/nagpra-procedure-claim.xml" merge="xmlmerge.properties" />
>                        <include src="base-procedure-conditioncheck.xml" />
>+                       <include src="base-procedure-osteology.xml,extensions/anthropology-procedure-osteology.xml" merge="xmlmerge.properties"/>
>                        <include src="base-procedure-exhibition.xml" />
>                        <include src="base-procedure-groups.xml" />
>                        <include src="base-procedure-intake.xml" />

This shows that one line was added to the configuration for the template tenant (in this example, the anthro tenant). Edit the configuration file for your tenant (in this example, tomcat-main/src/main/resources/mytenant-tenant.xml), and add the same line:

<include src="base-procedure-osteology.xml,extensions/anthropology-procedure-osteology.xml" merge="xmlmerge.properties"/>

Note that the changes will vary, depending on the template tenant. Some tenants may require no configuration changes.

If you created more than one tenant, repeat the above steps for each tenant.

Upgrade Tenant Front End (UI) Configuration

If you created a tenant in 5.1, the user interface for the tenant will be located in the old Tomcat 7 directory. Inside the webapps directory, there will be a directory named cspace#{tenant_short_name}, where {tenant_short_name} is the short name of your tenant. This directory should be copied into the services source directory, under cspace-ui, and the cspace# prefix should be removed from the name. For example, if your tenant's short name is mytenant:

cp -r /usr/local/share/apache-tomcat-7.0.64/webapps/cspace#mytenant ~/collectionspace-source/services/cspace-ui/mytenant

Make the following changes to the newly copied tenant UI directory.

Copy build.properties from the tenant that you used as a template for creating your tenant. For example, if the mytenant tenant was cloned from the anthro tenant:

cp ~/collectionspace-source/services/cspace-ui/anthro/build.properties ~/collectionspace-source/services/cspace-ui/mytenant

Edit index.html in your tenant UI directory. There will be two lines that contain <script> tags with a src attribute. Replace these lines with the corresponding lines from index.html in the tenant that you used as a template for creating your tenant. For example, if your tenant was cloned from the anthro tenant, the lines would be:

<script src="/cspace-ui/@UI_FILENAME@"></script>
<script src="/cspace-ui/@UI_PROFILE_PLUGIN_FILENAME@"></script>

If you created more than one tenant, repeat the above steps for each tenant.

Build and Deploy

Build and deploy CollectionSpace from the source code. The final ant command below includes the create_db target. This will not delete any existing data, because the -Drecreate_db=true parameter is not supplied. 

cd ~/collectionspace-source
cd services
mvn clean install -DskipTests
cd ../application
mvn clean install -DskipTests
cd ../services
ant undeploy deploy create_db import

Migrate Binary Data

Perform the following steps as the user you use to run CollectionSpace – typically, the cspace user

Move or copy the nuxeo-server/data directory from Tomcat 7 to Tomcat 8. This directory contains the binary data that was uploaded in CollectionSpace media records, so it can be large. Moving the directory instead of copying it is faster, and prevents unnecessary duplication; if you need to revert the upgrade, remember to move the directory back.

mv /usr/local/share/apache-tomcat-7.0.64/nuxeo-server/data /usr/local/share/apache-tomcat-8.5.40/nuxeo-server

Verify the Upgrade

Start CollectionSpace, being sure to use the startup script in the new Tomcat 8 directory, not the old Tomcat 7. Ensure that there are no errors in the logs during startup, and that you can log in to your tenant, and open and save records.