...

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 , or container commit are 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.

  Depending on how you installed ColllectionSpace, these might be in /home/cspace/collectionspace-source, or /

  These are typically in /opt/collectionspace. 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

  either 

  /

  usr/local/share/apache-tomcat-{version}, or /

  opt/collectionspace/apache-tomcat-{version}. Substitute {version} with the number that exists on your server. This will vary with the CollectionSpace version – for example, 8.5.51 for CollectionSpace

  6

  7.

  1

  2.

Before continuing, ensure that tomcat is not running.

Upgrading from CollectionSpace

...

7.

...

2

Tomcat

The tomcat server remains the same for v7.0. No upgrade is neededversion of Tomcat used for v8.0 remains 8.5.51, but the CollectionSpace tomcat distribution for v8.0 contains a configuration change that is required for proper functioning of the system. It is recommended to reinstall tomcat from the v8.0 tarball. To do so, perform the following steps as the user you use to build and deploy CollectionSpace – typically, collectionspace.

In the CollectionSpace installation directory, rename the existing tomcat directory.

cd /opt/collectionspace
mv apache-tomcat-8.5.51 tomcat-backup

Download and unpack the 8.0 tarball. This will recreate the tomcat directory.

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

Delete the tarball.

rm cspace-server-8.0.tar.gz

Keep the tomcat-backup directory in case you made any changes to it that you need to transfer to the new tomcat directory. It can be deleted after your CollectionSpace system has been upgraded and fully tested.

Upgrade Source Code

Perform the following steps as the user you use to build and deploy CollectionSpace – typically,

...

collectionspace.

CollectionSpace source code is normally located in /

...

opt/collectionspace.

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 /opt/collectionspace
cd services
git checkout tenant.properties
cd ../application
git checkout tenant.properties

Upgrade the source code to

...

8.0:

cd 

...

/

...

opt/collectionspace
cd services
git fetch
git checkout 

...

v8.0-branch
cd ../application
git fetch
git checkout 

...

v8.0-branch

Upgrade Tenant Back End (Services) Configuration

If you created a tenant in

...

7.

...

2, 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 theanthro tenant:

...

cd /opt/collectionspace
cd application/tomcat-main/src/main/resources/tenants
ls anthro
> anthro-authority-

...

chronology.xml  anthro-authority-person-termList.xml  domain-instance-vocabularies.xml
> anthro-authority-concept.xml     anthro-collectionobject.xml           settings.xml

...

cp anthro/anthro-authority-

...

chronology.xml 

...

mytenant/mytenant-authority-chronology.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/domain-instance-vocabularies.xml

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

...

7.

...

2 and

...

8.0. 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 /opt/collectionspace
cd application 
git diff -w 

...

origin/v7.

...

2-branch 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 

...

676667f2b..

...

ee7cb9900 100644
> --- a/tomcat-main/src/main/resources/anthro-tenant.xml
> +++ b/tomcat-main/src/main/resources/anthro-tenant.xml
> @@ -

...

80,

...

6 +

...

80,7 @@

...

>                         

...

<include src="base-

...

other-batchoutput.xml" />

...

...

>                         <include src="base-

...

other-invocationresults.xml" />

...

...

>                         <include src="base-

...

other-

...

searchall.xml" />

...

...

> +                       <include src="base-

...

other-

...

associatedauthority.xml" />

...

...

>                 

...

</records>
>         

...

</spec>
>  </cspace-config>

This shows that one change was made to the configuration for the template tenant (in this example, the anthro tenant) from

...

7.

...

2 to

...

8.0: One include line was

...

added. Make the same

...

change to the configuration file for your tenant (tomcat-main/src/main/resources/{tenant_short_name}-tenant.xml).

...

 Note that the results will vary, depending on the template tenant. Some tenants may require no configuration changes, and some tenants may require multiple 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

...

7.

...

2, the user interface for the tenant will be located in the services/cspace-ui directory. Inside that directory, there will be a directory named

...

with the short name of your tenant.

To upgrade your tenant, copy build.properties from the tenant that you used as a template for creating your tenant. For example, if the short name of your tenant is mytenant tenant, and your tenant was cloned from the anthro tenant:

cd /

...

opt/collectionspace
cd services/cspace-ui
cp anthro/build.properties mytenant

If you created more than one tenant, repeat 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 /opt/collectionspace
cd services
mvn clean install -DskipTests
cd ../application
mvn clean install -DskipTests
cd ../services
ant undeploy deploy create_db import

Verify the Upgrade

Start CollectionSpace. 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.