Installing CollectionSpace

Getting CollectionSpace

Go to the directory where you want to install CollectionSpace:

cd /usr/local/share

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

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

Make necessary files executable:

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

rm cspace-server-5.1.tar.gz

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

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:

ant undeploy deploy create_db -Drecreate_db=true import

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.

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:

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

3. 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"/>

4.  (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"/>

5.  Restart the CollectionSpace server

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