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.

Use your favorite FTP client to connect to the server: source.collectionspace.org
Use anonymous credentials (username anonymous and the password anything) with FTP.
Go to the directory pub/collectionspace/releases/4.3 and get the file:
Unknown macro: {multi-excerpt-include}
Copy this file to the directory in which you want to install CollectionSpace. For example, for the 4.3 release of CollectionSpace, copy
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:
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:

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.

LINUX / MAC OS X / UNIX environment variables

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.

Caution

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

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

In your web browser, visit the following URL: https://github.com/collectionspace/application/archive/v4.1.1.zip

Copy the downloaded file, from your browser's default downloads folder to %HOMEDRIVE%%HOMEPATH%\collectionspace-source

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

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.

Installing on Generic Unix-like or Windows Systems