Post-install step for upgrading to v5.0

Owned by Tom Jones
Jul 26, 2018
5 min read

These notes describe how to "upgrade" your newly installed v4.5 instance of CollectionSpace to version 5.0. These notes will be obsolete once the automated installer has been updated to install CollectionSpace v5.0.

To get CollectionSpace v5.0 pre-release up and running, first following the instructions for installing CollectionSpace v4.5.  Once you've successfully installed CollectionSpace v4.5 and feel confident it is up and running correctly, follow these instructions to update it to version 5.0.

If you have CollectionSpace v4.5 running, stop it.  Login to the linux server you're using to host CollectionSpace.  From the command line, switch to the 'cspace' user:

sudo su - cspace

Change your directory to the Apache Tomcat directory where CollectionSpace is installed:

cd /usr/local/share/apache-tomcat-7.0.64

Run the following command to stop the CollectionSpace web application:

./bin/shutdown.sh

Now change your working directory to the 'cspace' user's home:

cd ~

Next, we're going to update the CollectionSpace source code to version 5.0. Change your working directory to where you downloaded (via the 'git' command) the CollectionSpace sources:

cd collectionspace-source/

First, let's update the CollectionSpace Services code:

cd services

git checkout master

git pull

mvn clean install -DskipTests

The last command kicks off a full build of the CollectionSpace service layer code.  This will take 2-5 minutes depending on the speed of your server.  Once that complete sucessfully, we'll update the Application layer with these commands:

cd ../application

mvn clean install -DskipTests

 In version 5.0, the CollectionSpace user interface code is completely new, so we won't be updating the code in the old "ui" directory.  Therefore there's no need or reason to update the old v4.5 UI code.  Instead, we're going to install the new v5.0 CollectionSpace UI a little bit late.  For now, we need deploy the CollectionSpace v5.0 application and services with the following commands.  Switch back from the Application layer directory to the Services layer:

cd ../services

Now deploy the v5.0 services.  This could take up to 10 minutes depending upon the speed of your server.

ant undeploy deploy

The next step will erase ALL existing CollectionSpace user data.  Do not follow this step if you have existing v4.5 data.  The instructions on this page are only for upgrading a new installation of CollectionSpace v4.5.  There are separate instructions for upgrading from an existing, earlier version of CollectionSpace to v5.0.

Data Loss

The next step will erase ALL existing CollectionSpace user data.  Do not follow this step if you have existing v4.5 end-user data.

ant create_db -Drecreate_db=true import

Next, let's make some changes to the Apache Tomcat installation that you're using to manage the CollectionSpace v5.0 application.  In the Tomcat directory library directory (/use/local/share/apache-tomcat-7.0.64/lib), create a new file named "security.properties" that contains the following text:

# security.properties - Security settings for CollectionSpace.
#
# Cross-Origin Resource Sharing or CORS
# For more info: https://tomcat.apache.org/tomcat-7.0-doc/config/filter.html#CORS_Filter
# Examples:
#
# Don't allow cross-origin requests
#     cors.allowed.origins=
#
# If you help develop new CollectionSpace features, you may run the UI locally on port 8080, and Karma tests will originate from localhost:9876
#     cors.allowed.origins=http://localhost:8080,http://localhost:9876
#

## Example for putting CollectionSpace/Tomcat behind an Apache Web Server instance that handles SSL/TLS connections.  You must
# replace <your-domain> with your deployment domain -e.g., www.mymuseum.org, www.hatcollections.com, etc.
#cors.allowed.origins=https://<your-domain>
 
## By default, don't allow cross origin requests.
#
cors.allowed.origins=

For production deployments, please read the Apache documentation related to the CORS setting in this file.  See the URL link in the file for more information. 

CORS - Cross-Origin Resource Sharing

The cors.allowed.origins property in Tomcat's /lib/security.properties file  specifies the set of domains origins from which clients are allowed to make requests to a CollectionSpace server  instance. Cross-Origin Resource Sharing or CORS defines a way in which client-side web applications and a server can interact to safely determine whether or not to allow a cross-origin request. Most clients such as browsers use the  XMLHttpRequest  object to make a cross-domain request. This is especially true for client code written using JavaScript, like the CollectionSpace UI . For the  CollectionSpace Server  to support such requests  cors-allowed-origins  must be enabled on the server in the apache-tomcat/lib/security.properties file.

 

The next thing we'll do is download and install the new CollectionSpace v5.0 code.  Follow these steps.  As the 'cspace', change your working directory:

cd /usr/local/share/apache-tomcat-7.0.64/webapps

mkdir cspace#core

cd cspace#core

Get the latest version of the UI

The label/tag string for the latest version of the UI can be found here: https://github.com/collectionspace/cspace-ui.js (in the npm badge) Use that label string in the following instructions. For example, if the latest version string is "2.0.1-alpha" then where you find the string "1.0.0-alpha", replace it with the string "2.0.1-alpha".

Now create a new file named "index.html" inside the "cspace#core" directory.  Add the following text to that file:

<html>
<head>
        <meta charset="UTF-8">
</head>
<body>
        <div id="cspace"></div>
        <script src="/cspaceUI@1.0.0-alpha.min.js"></script>
        <script>
                cspaceUI({
                        basename: '/cspace/core',
                        prettyUrls: true,
                });
        </script>
</body>
</html>

Next, create a new directory inside the "cspace#core" directory named "WEB-INF".

mkdir WEB-INF

cd WEB-INF

Inside that new directory, create a file named "web.xml" and add this content:

<web-app xmlns="http://java.sun.com/xml/ns/javaee" version="3.0" metadata-complete="true">
        <filter>
                <filter-name>FallbackResourceFilter</filter-name>
                <filter-class>org.collectionspace.services.common.filter.FallbackResourceFilter</filter-class>
        </filter>
        <filter-mapping>
                <filter-name>FallbackResourceFilter</filter-name>
                <url-pattern>/*</url-pattern>
        </filter-mapping>
        <filter>
                <filter-name>ExpiresFilter</filter-name>
                <filter-class>org.apache.catalina.filters.ExpiresFilter</filter-class>
                <init-param>
                        <param-name>ExpiresDefault</param-name>
                        <param-value>access plus 12 hours</param-value>
                </init-param>
        </filter>
        <filter-mapping>
                <filter-name>ExpiresFilter</filter-name>
                <url-pattern>/*</url-pattern>
        </filter-mapping>
</web-app>

Swith to the base Tomcat directory and start the Tomcat server:

cd /usr/local/share/apache-tomcat-7.0.64

Now let's download a recent release of the new UI into Tomcat's "webapps/ROOT" directory.

cd webapps/ROOT/

wget https://unpkg.com/cspace-ui@1.0.0-alpha/dist/cspaceUI.min.js -O cspaceUI@1.0.0-alpha.min.js

The string "cspaceUI@1.0.0-alpha.min.js" in the URL needs to match the value from the <script> element of the "index.html" file we created earlier.

Assuming you've already built and deployed the Services layer, you're now ready to start Tomcat and see if everything is working.

cd /usr/local/share/apache-tomcat-7.0.64

./bin/startup.sh

Assuming everything started up without problems, you should be able to login to CollectionSpace with the new v5.0 UI at this URL:

http://localhost:8180/cspace/core/login

As of Feb. 1 2017, only the "core" tenant is working.