WARNING

This is in-progress documentation of an UNRELEASED version of CollectionSpace.

These instructions have not been recently tested.

Save time when installing!

An automated, unattended installer for CollectionSpace is now available for testing. This installer can save you considerable time and effort, when compared to the manual installation steps below.

To try it out for yourself, please visit Automated installer for CollectionSpace.

These installation instructions should be compatible with Linux distributions using the Yum package manager, including Red Hat, Fedora, CentOS, Mandrake, and Yellow Dog.

Installing Prerequisites

Make sure you are super user:

Installing Ant, Maven, ImageMagick and FTP clients

Install the prerequisites available via Yum:

Installing the database

REQUIRED: although the details regarding this step are presented on a separate page, they are mandatory for the install to work.

Follow the install instructions for PostgreSQL on PostgreSQL Installation under Linux. The mandatory steps are Installation and Setting Up.

Optionally you can also do the Tuning step to tweak the database and improve performance.

Installing Java JDK

Unknown macro: {multi-excerpt}

First, check whether Java 7 is already installed:

java -version

You should expect output similar to the following, which lists a Java version that starts with 1.7. (the "1.7" refers to Java 7):

java version "1.7.0_13"
Java(TM) SE Runtime Environment (build 1.7.0_13-b20)
Java HotSpot(TM) 64-Bit Server VM (build 23.7-b01, mixed mode)

If instead, you see a message containing:

java version "1.6..." (or anything else earlier than 1.7)

or you encounter this message

java: command not found

then it is likely that you will need to install one of the latest Java 7 JDKs.

You will need need to download and install either the Java 7 OpenJDK or Oracle's Java Development Kit (JDK) manually. Make sure you get JDK 7 and not 6; and the JDK (a Java package that includes a development kit as well as a runtime environment), not the JRE (runtime environment alone).

Note: Depending on your system's access permissions, you may need root (e.g. sudo) privileges to perform most or all of following actions.

To install the Java 7 OpenJDK, execute the following command:

sudo apt-get install openjdk-7-jdk

Check that it is properly installed with:

java -version

You should now expect output similar to the following:

java version "1.7.0_13"
Java(TM) SE Runtime Environment (build 1.7.0_13-b20)
Java HotSpot(TM) 64-Bit Server VM (build 23.7-b01, mixed mode)

To install Oracle's Java Development Kit (JDK), follow these instructions:

Open a browser and go to http://www.oracle.com/technetwork/java/javase/downloads/index.html.

Find JDK7 (not JDK 6)
Click the "Download JDK" button" in the "Java Platform, Standard Edition" box.
Click the "Accept License Agreement" radio button.
Find the appropriate download link for your system. This link's text will:
- Contain linux
- End in .rpm (not .tar.gz)
- Contain either x64 or i586 depending on whether your Linux distribution is 64-bit or 32-bit, respectively.
  To find out which distribution you have, 64-bit or 32-bit, at a Terminal (shell) command line, enter:
  uname -p
  A 64-bit system will report x86_64, while a 32-bit system will report something like i386, i486, i586, or i686.
Click the appropriate download link.

This should let you download the JDK.

Run that file. (In the command below, the filename jdk-7u13-linux-x64.rpm is used as an example, representing the installer for Java 7 update 13, for 64-bit Linux systems. Please substitute the actual filename of the .rpm file you downloaded.)

rpm -Uvh jdk-7u13-linux-x64.rpm

You can safely ignore any Error: Could not open input file: {file_pathname}.pack messages.

Under Ubuntu or other Debian Linux-based systems, if you encounter this error (or a similar error):

The program 'rpm' is currently not installed.

See this comment for alternative download and installation instructions.

Check that it is properly installed with:

java -version

You should now expect output similar to the following:

java version "1.7.0_13"
Java(TM) SE Runtime Environment (build 1.7.0_13-b20)
Java HotSpot(TM) 64-Bit Server VM (build 23.7-b01, mixed mode)

If after following the steps above, the reported version of Java is for some reason incorrect, you can manually correct this via your Linux 'alternatives' mechanism. This allows you to specify that several key Java commands, including the all-important java and javac commands, should always be run from your newly-installed copy of Java 7, instead of being run from some older version of Oracle's Java or from a version of OpenJDK, if either/both might also be installed on your system:

update-alternatives --install /usr/bin/java java /usr/java/latest/bin/java 20000
update-alternatives --install /usr/bin/javac javac /usr/java/latest/bin/javac 20000

(By convention, if you've installed Java by running the rpm command, the path /usr/java/latest should always point to the latest installation of Java on your system, according to one of Oracle's JDK RPM Installation for Linux installation guides. If that directory does not exist on your system, you should substitute the actual filesystem paths to your java and javac commands; for example, /usr/lib/jvm/jdk1.7.0_25/java and /usr/lib/jvm/jdk1.7.0_25/javac for an installation of Java 7, Update 25 in one recent installation on an Ubuntu system, wherever you see /usr/java/latest/bin/java or /usr/java/latest/bin/javac in the relevant commands, both above and below.)

You can then choose to make the key java and javac commands point to your newly-installed copy of Java 7, by:

Entering each of the following commands in succession.
When prompted, typing the number (0, 1, 2 ...) next to the options that mention /usr/java/latest/bin/java and /usr/java/latest/bin/javac, respectively (or the actual filesystem paths to your java and javac commands):

update-alternatives --config java

and

update-alternatives --config javac

Check the Java version again by executing:

java -version

You should now see output similar to the following:

java version "1.7.0_13"
Java(TM) SE Runtime Environment (build 1.7.0_13-b20)
Java HotSpot(TM) 64-Bit Server VM (build 23.7-b01, mixed mode)

You can find more detailed instructions on installing Java under Linux at: http://www.oracle.com/technetwork/java/javase/index-137561.html#linux

Unknown macro: {multi-excerpt}

Installing CollectionSpace

Getting CollectionSpace

Go to the directory where you want to install CollectionSpace:

cd /usr/local/share

Download the tarball via FTP:

ftp nightly.collectionspace.org

Log in with the username anonymous and any password. Then:

Unknown macro: {code-custom}

cd pub/collectionspace/releases/

Unknown macro: {multi-excerpt-include}

get

Unknown macro: {multi-excerpt-include}

exit

Tip

The tarball can also be accessed by using Firefox or Chrome's built-in ftp client by typing the full ftp directory into the navigation bar

Unknown macro: {code-custom}

ftp://nightly.collectionspace.org/pub/collectionspace/releases/

Unknown macro: {multi-excerpt-include}

/

Unknown macro: {multi-excerpt-include}

Additionally, some virtual machines may give an error when attempting to get the tarball from the ftp server:

500 Illegal PORT command.
ftp: bind: Address already in use

A work around is to use the wget utility to download the tarball from the ftp server

Unknown macro: {code-custom}

wget ftp://nightly.collectionspace.org/pub/collectionspace/releases/

Unknown macro: {multi-excerpt-include}

/

Unknown macro: {multi-excerpt-include}

Unpack tarball:

Unknown macro: {code-custom}

tar -zxvof

Unknown macro: {multi-excerpt-include}

This will create an apache-tomcat-7.0.57 directory.

Make necessary files executable:

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

Optionally remove the tarball:

Unknown macro: {code-custom}

rm

Unknown macro: {multi-excerpt-include}

Setting up CollectionSpace

You need an administrative user account in PostgreSQL that CollectionSpace can use: one that has been granted full privileges and can grant privileges to other users. You can either set up a new user account (recommended), or use the postgres user account that you already set up in the prerequisites section of this page. The values myusername and mypassword, below, should be replaced by the actual username and password of this user.

Set up environment variables. 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.
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. If you are unsure where this variable should point to, you can execute this command: readlink -f `which java` and take the part that comes before 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.

The example below is for the Bash shell; edit ~/.bashrc or ~/.bash_profile and be sure to substitute the actual values for your environment:

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.6.0_30"
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"

Open (eg. execute bash) or log into a shell where these environment variables are active (to verify, type env).

Configure your tenant

CollectionSpace

Unknown macro: {multi-excerpt-include}

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.

Unknown macro: {code-custom}

cd $HOME
mkdir collectionspace-source
cd collectionspace-source
wget https://github.com/collectionspace/application/archive/v

Unknown macro: {multi-excerpt-include}

.tar.gz
tar -zxvof v

Unknown macro: {multi-excerpt-include}

.tar.gz
rm v

Unknown macro: {multi-excerpt-include}

.tar.gz
mv

Unknown macro: {multi-excerpt-include}

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.

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

tomcat-main/src/main/resources/tenants/{tenantname}/settings.xml, where {tenantname} is replaced by the actual name of the tenant;

The example below is for editing the settings file for the core tenant:

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:

Unknown macro: {code-custom}

mvn clean install -DskipTests

(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, $HOME/.m2/repository, on most Linux systems.)

Initialize database and users and permissions

Unknown macro: {code-custom}

cd $HOME/collectionspace-source
wget https://github.com/collectionspace/services/archive/v

Unknown macro: {multi-excerpt-include}

.tar.gz
tar -zxvof v

Unknown macro: {multi-excerpt-include}

.tar.gz
rm v

Unknown macro: {multi-excerpt-include}

.tar.gz
mv

Unknown macro: {multi-excerpt-include}

services
cd services

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.

You are now done with the most basic install.

Starting the server

Start the server:

$CSPACE_JEESERVER_HOME/bin/startup.sh

Wait for it to fully start up. (For more information on verifying server startup, see [Starting Up CollectionSpace Servers].)

Logging in

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.

For the lifesci tenant, go to: http://<ip-address>:8180/collectionspace/ui/lifesci/html/

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

Unknown macro: {multi-excerpt-include}

Unknown macro: {multi-excerpt-include}

Enabling access logging (optional)

Unknown macro: {multi-excerpt-include}

Unknown macro: {multi-excerpt-include}

Unknown macro: {multi-excerpt}

...And you're done

If you experienced troubles with the installation there are some resources to help you out:

Troubleshooting Installation Problems
[Use the highly active Talk mailing list]. The Talk list is appropriate for installation questions and problem reports.
Install Troubleshooting Forum
Installing CollectionSpace

Browser not supported