CollectionSpace Installation Guide

This Installation Guide provides instructions for individuals and organizations to plan, download, install and configure the CollectionSpace software used to manage museum collections. Follow the steps shown in the next sections to obtain, install and begin using the software in your environment, on a generic Unix-like or Windows system.

System Requirements

Planning for your CollectionSpace installation requires that you first gather information about the computer/server and network upon which the CollectionSpace software is installed and run. The CollectionSpace system requires:

A server running the CollectionSpace system that manages the data.
One or more clients, running a web browser, that request, process, and present data using a web-based interface.

Your first step should be to ensure that all System Requirements for a CollectionSpace Server have been met.

Download

The required files for installing CollectionSpace are available on the CollectionSpace FTP server. Once retrieved, they need to be unpacked. The following steps take you through that process.

wget https://s3-us-west-2.amazonaws.com/cs-public-shared-files/releases/5.1/cspace-server-5.1.tar.gz
cspace-server-5.1.tar.gz
Copy this file to the directory in which you want to install CollectionSpace. For example, for the 4.3 release of CollectionSpace, copy
```
cspace-server-4.3.tar.gz
```
to your installation directory. (For instance, on a generic Unix-like system, you might copy this file to {{/usr/local/share}}.)
Navigate to the installation directory containing this tar.gz file.
Run a GNU-compatible tar utility (for example, tar, winzip, 7-zip) to unpack the tar.gz file. For example, using the tar command:
```
tar -zxvof cspace-server-4.3.tar.gz
```
After the tar.gz files are unpacked, a new subdirectory named apache-tomcat-7.0.57 is created. This is your Tomcat home directory, and will contain the CollectionSpace system.

Set Linux/Mac script file permissions

Under Linux, Mac OS X, and other Unix-like operating systems, you will need to set the permissions of several Tomcat script files to executable for the user or group that will start the CollectionSpace servers. If you are in the directory in which you've just unpacked the tar.gz file, do this using the following command:

chmod u+x apache-tomcat-7.0.57/bin/*.sh

SUMMARY — DOWNLOAD

You have now downloaded and unpacked the files you need to use to install the CollectionSpace server. The next section provides instruction on how to install and deploy CollectionSpace.

Install and Deploy

There are several steps to undertake to install and deploy CollectionSpace.

Set environment variables

Set up environment variables in your command environment or shell. Make sure that the following values correspond to your environment:

The names of three environment variables changed between CollectionSpace versions 4.0 and 4.1. In addition, one new environment variable was added, and one old variable was deleted. These changes are reflected in the instructions below. See Updating environment variables when migrating to CollectionSpace 4.1 or higher for details.

CSPACE_JEESERVER_HOME: The full path to the apache-tomcat-6.0.33 directory that was created when you unpacked the CollectionSpace tarball.
CATALINA_HOME: The full path to the apache-tomcat-6.0.33 directory, identical to the value of CSPACE_JEESERVER_HOME.
CATALINA_PID: The full path to a file which will hold the Tomcat server process number. This is used by the Tomcat shutdown script. (You may not need to set this environment variable under Windows.)
CATALINA_OPTS: Environment options for the Tomcat server process. The recommended options below are Java Virtual Machine (JVM) memory settings which permit allocation of up to 1 GB of RAM to the Java heap and up to 384 MB of RAM for Java Permanent Generation (PermGen) space.
JAVA_HOME: The full path to your Java directory. On a generic Unix-like system, if you are unsure where this variable should point to, you can execute the command readlink -f `which java` and take the beginning part of this path that comes before bin or jre.
DB_CSADMIN_PASSWORD: The password for the administrative database user for the CollectionSpace application. This must match the password for that user that you specified while setting up PostgreSQL, via the instructions in PostgreSQL Installation under Linux. (This administrative user by default will be named csadmin, and will be a superuser. However, this user will have fewer privileges than the overall database administrator superuser, by default named postgres.)
DB_NUXEO_PASSWORD: Any database-legal password of your choice for the nuxeo database user. This user can work with CollectionSpace data stored in Nuxeo, the content management system underlying CollectionSpace.
DB_CSPACE_PASSWORD: Any database-legal password of your choice for the cspace database user. This user can work with CollectionSpace data for users, roles, and access permission.
DB_READER_PASSWORD: Any database-legal password of your choice for the reader database user. This user will have read-only access to CollectionSpace data stored in Nuxeo.
ANT_OPTS: Environment options for the Apache Ant build tool. The recommended options below are Java Virtual Machine (JVM) memory settings which permit allocation of up to 768 MB of RAM to the Java heap and up to 512 MB of RAM for Java Permanent Generation (PermGen) space.
MAVEN_OPTS: Environment options for the Maven build tool. The recommended options below are Java Virtual Machine (JVM) memory settings which permit allocation of up to 768 MB of RAM to the Java heap and up to 512 MB of RAM for Java Permanent Generation (PermGen) space.
CSPACE_INSTANCE_ID: String appended to default CollectionSpace database names.
DB_HOST: The hotname or IP address of the server running Postgres.
DB_PORT: The port for the Postgresql service. Usually 5432
JEE_PORT: The HTTP port for the CollectionSpace services (usually 8180)

Below are examples for setting these environment variables in Windows and Linux.

Windows environment variables

If your server is running Windows, the next commands will set those environment variables:

Caution

Make sure to change the values below to those appropriate to your own system.

set CSPACE_JEESERVER_HOME=C:\dev\apache-tomcat-6.0.33
set CATALINA_HOME=%CSPACE_JEESERVER_HOME%
set CATALINA_OPTS="-Xmx1024m -XX:MaxPermSize=384m"
set JAVA_HOME=C:\Program Files\Java\jdk1.7.0_13
set DB_CSADMIN_PASSWORD="your_csadmin_database_user_password_here"
set DB_NUXEO_PASSWORD="your_nuxeo_database_user_password_here"
set DB_CSPACE_PASSWORD="your_cspace_database_user_password_here"
set DB_READER_PASSWORD="your_reader_database_user_password_here"
set ANT_OPTS=-Xmx768m -XX:MaxPermSize=512m
set MAVEN_OPTS= -Xmx768m -XX:MaxPermSize=512m
set DB_HOST=localhost
set DB_PORT=5432
set JEE_PORT=8180

If your server is running Linux, Mac OS X or another Unix-like system, and is using the `bash` shell, the next commands will set the environment variables.LINUX / MAC OS X / UNIX environment variables

Caution

Make sure to change the values below to those appropriate to your own system.

export CSPACE_JEESERVER_HOME="/usr/local/share/apache-tomcat-6.0.33"
export CATALINA_HOME=$CSPACE_JEESERVER_HOME
export CATALINA_PID="$CSPACE_JEESERVER_HOME/bin/tomcat.pid"
export CATALINA_OPTS="-Xmx1024m -XX:MaxPermSize=384m"
export JAVA_HOME="/usr/java/jdk1.7.0_13"
export DB_CSADMIN_PASSWORD="your_csadmin_database_user_password_here"
export DB_NUXEO_PASSWORD="your_nuxeo_database_user_password_here"
export DB_CSPACE_PASSWORD="your_cspace_database_user_password_here"
export DB_READER_PASSWORD="your_reader_database_user_password_here"
export ANT_OPTS="-Xmx768m -XX:MaxPermSize=512m"
export MAVEN_OPTS="-Xmx768m -XX:MaxPermSize=512m"
export DB_HOST=localhost
export DB_PORT=5432
export JEE_PORT=8180

The commands above will temporarily set these environment variables. To set these environment variables persistently, refer to your operating system documentation on how to do so via a control panel or application, or by editing a configuration file.

Configure your tenant

CollectionSpace 4.3 ships with two demonstration tenants: core and lifesci. Below, you will be using the core tenant as an example. But be aware that the second lifesci tenant is also active and configurable.

Windows

cd %HOMEDRIVE%%HOMEPATH%
mkdir collectionspace-source
cd collectionspace-source

Copy the downloaded file, from your browser's default downloads folder to %HOMEDRIVE%%HOMEPATH%\collectionspace-sourceIn your web browser, visit the following URL: https://github.com/collectionspace/application/archive/v4.1.1.zip

A command line alternative (untested) for downloading this file directly into that folder, using PowerShell in Windows Vista and above:

powershell -command "& { (new-object System.Net.WebClient).DownloadFile('https://github.com/collectionspace/application/archive/v4.3.zip','%HOMEDRIVE%%HOMEPATH%\v4.3.zip') }"

unzip v4.3.zip
del v4.3.zip
rename application-4.3 application
cd application

In the set of steps above, you'll notice that there is a step to delete the original archive file you just downloaded (for example, via wget) immediately after it is expanded. This step is required in order to permit a later part of the installation to succeed: where you will download an identically named file, with different contents, to the same directory.

Linux, Mac OS X, or Unix

cd $HOME
mkdir collectionspace-source
cd collectionspace-source
wget https://github.com/collectionspace/application/archive/v4.3.tar.gz 
tar -zxvof v4.3.tar.gz
rm 4.3.tar.gz
mv application-4.3 application
cd application

In the set of steps above, the step that involves deleting the just-downloaded archive file is required. This permits a later part of the installation - in which you will download an identically named file with different contents - to succeed.

Continuing on Windows, Linux, Mac OS X, and Unix

The settings file for a tenant is located inside the application folder:

Windows:

tomcat-main\src\main\resources\tenants\{tenantname}\settings.xml

Linux, Mac OS X, or Unix:

tomcat-main\src\main\resources\tenants\{tenantname}\settings.xml

where {tenantname} is replaced by the actual name of the tenant.

Edit this file. (The example below is for editing the settings file for the core tenant, using the vi editor in Linux, Mac OS X, or Unix; you can use an equivalent command to edit this file in your favorite plain text editor in Windows.)

vi tomcat-main/src/main/resources/tenants/core/settings.xml

In the <settings><email><baseurl> setting, enter your server's Internet host address (its hostname or IP address). The baseurl will be the beginning part of the URL which a user can visit to reset their password:
```
<email>
    <baseurl>http://yourserverhostnamehere:8180</baseurl>
```

In the <settings><email><from> setting, enter an email address. This will be the email address in the From: line of password reset emails; e.g.
```
<from>youremail@example.com</from>
```

In the <settings><persistence><service><url> setting, verify the server address of the CollectionSpace services layer. This is the address of the back-end part of CollectionSpace that stores data, such as cataloging and procedural records. (Usually this is running on your own host and you can simply leave the default value of localhost here.)

Build the Application layer and deploy (copy) your changes to the CollectionSpace server. A first-time build can take approximately 5-10 minutes on a typical system; subsequent builds will be considerably faster:

mvn clean install -DskipTests

Initialize the databases and import default users and permissions(During this process, you may notice a large number of dependency-related files being downloaded, as well. These files will be downloaded to your local Maven repository directory, C:\Documents and Settings\\{your-username}\.m2 on most Windows systems, and $HOME/.m2/repository, on most Linux and Mac OS X systems.)

Downloading source code on Windows

cd %HOMEDRIVE%%HOMEPATH%\collectionspace-source

Copy the downloaded file, from your browser's default downloads folder to %HOMEDRIVE%%HOMEPATH%\collectionspace-sourceIn your web browser, visit the following URL: https://github.com/collectionspace/services/archive/v4.3.zip

A command line alternative (untested) for downloading this file directly into that folder, using PowerShell in Windows Vista and above:

powershell -command "& { (new-object System.Net.WebClient).DownloadFile('https://github.com/collectionspace/services/archive/v4.3.zip','%HOMEDRIVE%%HOMEPATH%\v4.3.zip') }"

unzip v4.3.zip
del v4.3.zip
rename services-4.3 services
cd services

Downloading source code on Linux, Mac OS X, or Unix

cd $HOME/collectionspace-source
wget https://github.com/collectionspace/services/archive/v4.3.tar.gz 
tar zxvof v4.3.tar.gz 
rm v4.3.tar.gz 
mv services-4.3 services
cd services

Continuing on Windows, Linux, Mac OS X, and Unix

Enter the following command to build the CollectionSpace Services layer. A first-time build can take approximately 10 minutes on a typical system; subsequent builds will be considerably faster:
```
mvn clean install -DskipTests
```

Enter the following command to initialize the CollectionSpace databases and import a default set of users and permissions. This can take approximately 10-15 minutes on a typical system:
Warning

The ant create_db -Drecreate_db=true command deletes any existing databases named 'nuxeo' and 'cspace' before it creates empty new databases using those names. If you have any databases matching these names, make sure to first rename them or back them up before running that command.
```
ant undeploy deploy create_db -Drecreate_db=true import
```

Tip

If an error occurs during any of these 'ant' commands, you can usually find a relevant error message near the end of the output from running that command.

Start the servers

Start the Collection Space servers by typing the relevant command for your operating system, as listed in this document:

Starting Up the CollectionSpace Server

These instructions include verification procedures to ensure that the start up was successful.

Test logging into the server

Check the installation: Open a browser and go to this URL http://<ip-address>:8180/collectionspace/ui/core/html/

You should be able to log in to the demonstration core tenant using the user admin@core.collectionspace.org and the password Administrator.

Initializing default authorities and term lists

In order to make a newly-created tenant fully functional, you must initialize data for that tenant. The process of initializing data involves reading configuration files in CollectionSpace's Application layer and, from that configuration, creating:

A set of authorities, which will hold authority terms for persons, organizations, storage locations, and the like. Initializing this data is necessary to be able to save authority term records (Person, Storage Location, Concept, etc.), as well as to enable "autocomplete" fields, in which you can type into a field and be presented with suggestions for matching terms.
A set of vocabularies, along with lists of terms in each of these vocabularies. Initializing this data is necessary to populate the options that appear in certain drop down menus.

The process of initializing authorities and vocabularies/term lists involves two steps:
1. Logging into the tenant in which you wish to initialize data.
2. Visiting a specific URL to begin the initialization process. (You'll then see on-screen messages describing its progress.)

For instance, when you install a brand-new CollectionSpace system, you'll need to initialize data for the demonstration core tenant. To do so:

Make sure you are logged into the core tenant, then enter this URL in a browser:
http://<ip-address>:8180/collectionspace/tenant/core/authorities/initialise

For Linux, Mac OS X, and other Unix-like systems, there is also a shell script available to automate the process of initializing default authorities and term lists for one or more tenants. You can optionally run that script as an alternative to the manual process described above.

Populating with sample records

You can optionally choose to populate a CollectionSpace tenant with a set of sample records. These include over 2,000 authority term records for persons and organizations.

Typically you would only populate a demonstration or "play" tenant with sample records, to avoid intermingling sample records with "real" records. To populate the demonstration core tenant with sample records:

Make sure you are logged into the core tenant, then enter this URL in a browser:
http://<ip-address>:8180/collectionspace/tenant/core/reset

This process of adding sample data is time consuming - it can take 20 minutes or more. During that time, you will see a succession of progress messages in your browser window.

Enabling access logging - which is turned off by default - is a recommended best practice. Logging accesses to your CollectionSpace system can often help you troubleshoot configuration, operational, security, and performance issues.

Procedure

To enable access logging:

If the CollectionSpace server is running, stop the server
Edit the file $CSPACE_JEESERVER_HOME/conf/server.xml (or %CSPACE_JEESERVER_HOME%\conf\server.xml on a Windows system).

Uncomment the AccessLogValve directive in this file, by removing any XML comment markers (<!-- and –>) that may be present around that section:

<Valve className="org.apache.catalina.valves.AccessLogValve" directory="logs" prefix="localhost_access_log." suffix=".txt" pattern="common" resolveHosts="false"/>

(Optional) To add round-trip timings to access log entries, identifying how long each request to your CollectionSpace system took to process and send a response, change the value of the pattern= attribute from "common" to the pattern value below, exactly as shown:
```
<Valve className="org.apache.catalina.valves.AccessLogValve" directory="logs" prefix="localhost_access_log." suffix=".txt"  pattern="%h %l %u %t &quot;%r&quot; %s %b %T" resolveHosts="false"/>
```
Restart the CollectionSpace server

Browser not supported