Save time when installing!

An automated, unattended installer for CollectionSpace is available. 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 a super user:

su

Installing Ant, Maven, ImageMagick and FTP clients

Install the prerequisites available via Yum:

yum install ant maven ImageMagick ftp

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

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

Installing CollectionSpace

Getting CollectionSpace

Go to the directory where you want to install CollectionSpace:

cd /usr/local/share

Download the tarball:

wget https://s3-us-west-2.amazonaws.com/cs-public-shared-files/releases/5.1/cspace-server-5.1.tar.gz

Unpack tarball:

tar -zxvof cspace-server-5.1.tar.gz

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:

rm cspace-server-5.1.tar.gz

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 thepostgresuser account that you already set up in the prerequisites section of this page. The valuesmyusernameandmypassword, 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 theapache-tomcat-6.0.33directory that was created when you unpacked the CollectionSpace tarball.
CATALINA_HOME: The full path to theapache-tomcat-6.0.33directory, identical to the value ofCSPACE_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 beforejre.
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 inPostgreSQL Installation under Linux. (This administrative user by default will be namedcsadmin, and will be a superuser. However, this user will have fewer privileges than the overall database administrator superuser, by default namedpostgres.)
DB_NUXEO_PASSWORD:Any database-legal password of your choice for thenuxeodatabase 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 thecspacedatabase 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 thereaderdatabase 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~/.bashrcor~/.bash_profileand 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. executebash) or log into a shell where these environment variables are active (to verify, typeenv).

Configure your tenant

CollectionSpace 5.2 ships with two demonstration tenants:coreandlifesci. Below, you will be using thecoretenant as an example. But be aware that the secondlifescitenant is also active and configurable.

cd $HOME 
mkdir collectionspace-source 
cd collectionspace-source 
wget https://github.com/collectionspace/application/archive/v5.1.tar.gz 
tar -zxvof v5.1.tar.gz 
rm v5.1.tar.gz 
mv application-5.1 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, viawget) immediately after it is expanded. This step isrequiredin 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 theapplicationfolder:

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). Thebaseurlwill 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 theFrom: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 oflocalhosthere.)

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

(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

cd $HOME/collectionspace-source wget https://github.com/collectionspace/services/archive/v5.1.tar.gz tar -zxvof v5.1.tar.gz rm v5.1.tar.gz mv services-5.1 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

Theant create_db -Drecreate_db=truecommanddeletes 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, seeStarting Up CollectionSpace Servers.)

Logging in

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

You should be able to log in to the demonstrationcoretenant using the useradmin@core.collectionspace.organd the passwordAdministrator.

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

...And you're done

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

Troubleshooting Installation Problems
Send a note to talk@lists.collectionspace.org. The Talk list is appropriate for installation questions and problem reports.
Installing CollectionSpace

Browser not supported