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.

1. 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}

2. 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}}.)

3. Navigate to the installation directory containing this tar.gz file.

4. Run a GNU-compatible tar utility (for example, tar, winzip, 7-zip) to unpack the tar.gz file. For example, using the tar command:

   
5. 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.

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:

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:

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.

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:

Linux, Mac OS X, or Unix

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:

(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.)

Initialize the databases and import default users and permissions

Downloading source code on Windows

In your web browser, visit the following URL: https://github.com/collectionspace/services/archive/v4.3.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:

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

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

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.

Enabling access logging (optional)