WARNING

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

These instructions have not been recently tested.

Last tested on (possibly with earlier CollectionSpace release):
October 2012: OS X 10.8 (Mountain Lion)
The "Installing Prerequisites" instructions, after being updated, have been tested once again in February 2013 with OS X 10.8.2.

Installing Prerequisites

Make sure you are a logged in as a user with Administrative rights and sudo privileges.

Installing Xcode

Unknown macro: {multi-excerpt}

Beginning with OS X 10.9 ("Mavericks"), it may be possible (as yet unverified) for you to install the XCode command line tools via a single command, rather than having to complete all of the steps below. See Installing Homebrew in Mac OS X 10.9 (Mavericks).

Tools for compiling and building source code aren't included by default on recent versions of Mac OS X. Apple's free Xcode suite of tools provides these tools, and you will first need to install it.

To install Xcode and its command line tools:

Open the App Store application. (You can find it in your /Applications folder.)
Search for Xcode.
Click the appropriate link(s) to download and install Xcode. (Note: this is a large download, fully 1.65 GB for Xcode 4.6, for example.)
Install the Xcode command line tools:
- Open the Xcode application. (You can find it, once it has been installed, in your /Applications folder.)
- If this is a first-time installation of Xcode:
  - Accept the License Agreement.
  - Download any suggested components at the System Component Installation screen.
- Select Preferences ... from the Xcode menu.
- Click the Downloads icon.
- Install the Command Line Tools from the Downloads->Components tab.

Updating Mac OS X

Select Software Update... from the Apple menu. Among other things, this will guide you through:

Updating Mac OS X to version 10.8.2, or to whatever may be the latest version of Mac OS X 10.8 ("Mountain Lion") as of this writing.
Applying the latest Apple security updates to your operating system.

Performing a Software Update will also help ensure that you will have updated copies of certain other CollectionSpace installation prerequisites, such as the Ant and Maven build tools.

Installing Java

Unknown macro: {multi-excerpt}

To install Java 7:

Visit Oracle's Java SE download page
Click any of the Java Platform (JDK) 7u... Download buttons on that page.
Click the Accept License Agreement button.
Follow the next steps described in Oracle's guide, How do I install Java for my Mac?:
- One minor but important change from that guide: you'll be downloading a file whose name begins with jdk, rather than jre as described in the guide.
  (As of this writing, the file you will want to download is named jdk-7u13-macosx-x64.dmg: the Java Development Kit (JDK) for Java 7 Update 13.)

Installing ImageMagick

ImageMagick is a graphics package required by the CollectionSpace system for displaying and manipulating images.

Linux users have the benefit of using built-in package managers - tools that install software packages - to install many of the necessary prerequisites for installing CollectionSpace.

Mac OS X does not come with a built-in package manager. Instead, the following steps will first install Homebrew, an easy and lightweight package manager, as a means to install ImageMagick.

Run the Homebrew install script:

For more information on installing Homebrew, see the "Install Homebrew" section of the Homebrew home page.

Next, install Git, a fast version control system used by Homebrew, to initiate the installation of ImageMagick:

Next, install a package that includes a shared library required by ImageMagick:

Finally, install ImageMagick:

If you plan to upload TIFF images to your CollectionSpace system, you may need to instead:

If for any reason your ImageMagick installation via Homebrew fails, try:

Diagnosing Homebrew issues by entering brew doctor inside your Homebrew Library directory (e.g. inside /usr/local/Library on some systems), and resolving any issues found by following the instructions provided.
Using a third-party ImageMagick installer from Cactuslab. This installation includes TIFF support.

Installing the PostgreSQL database server

REQUIRED: Although the next steps are in a separate page, they are mandatory for the install to work.

Follow the instructions for installing and setting up the PostgreSQL server on this page. After installing and setting up the PostgreSQL server, return to this page and complete the remaining CollectionSpace-related installation steps below.

Installing CollectionSpace

Unknown macro: {multi-excerpt}

Getting CollectionSpace

Go to the directory where you want to install CollectionSpace:

cd /usr/local/share

Download the tarball via FTP:

ftp source.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://source.collectionspace.org/pub/collectionspace/releases/

Unknown macro: {multi-excerpt-include}

/

Unknown macro: {multi-excerpt-include}

TIP: If you find that you are denied permission to save the tarball in your current directory, either change the permissions of that directory or try reconnecting to the source.collectionspace FTP server using the 'sudo ftp' command. (Provide your local machine password when prompted by 'sudo'.)

Unpack tarball:

Unknown macro: {code-custom}

tar zxvof

Unknown macro: {multi-excerpt-include}

This will create an

Unknown macro: {multi-excerpt-include}

directory.

Your account will need to have write permission to the newly-created

Unknown macro: {multi-excerpt-include}

directory and all of its subdirectories. You can test this by trying to touch or edit a file in that directory tree (but make sure you are not currently su or sudo).

If you do not have write permissions, you can chown -R the entire directory tree to your user; e.g. sudo chown -R myusername:mygroup apache-tomcat-6.0.33

Optionally remove the tarball:

Unknown macro: {code-custom}

rm

Unknown macro: {multi-excerpt-include}

Make necessary files executable:

Unknown macro: {code-custom}

chmod u+x

Unknown macro: {multi-excerpt-include}

/bin/*.sh

Unknown macro: {multi-excerpt}

Setting up CollectionSpace

You need an administrative user in PostgreSQL that CollectionSpace can use: one that has been granted full privileges and can grant privileges to other users. Either set up a new user account (recommended), or you can use the postgres user that you 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:

Tip

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

Unknown macro: {multi-excerpt-include}

directory that was created when you unpacked the CollectionSpace tarball.
CATALINA_HOME: The full path to the

Unknown macro: {multi-excerpt-include}

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. Apple recommends that you set this to the output of running the command /usr/libexec/java_home, and by entering that command surrounded with backticks (`), as shown below, you can do that automatically.
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:

Unknown macro: {code-custom}

export CSPACE_JEESERVER_HOME="/usr/local/share/

Unknown macro: {multi-excerpt-include}

"
export CATALINA_HOME=$CSPACE_JEESERVER_HOME
export CATALINA_PID="$CSPACE_JEESERVER_HOME/bin/tomcat.pid"
export CATALINA_OPTS="-Xmx1024m -XX:MaxPermSize=384m"
# Note that the JAVA_HOME declaration below uses backticks (`), rather than double quote marks:
export JAVA_HOME=`/usr/libexec/java_home`
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"

If you added these lines to ~/.bashrc, to ensure these environment variables are present in every new login shell, edit or create the ~/.bash_profile file and add the following line to that file:

. ~/.bashrc

Next, the path for PostgreSQL's binaries need to be added to the shell PATH environment.
Mac OS X sets the PATH environmental variable not in ~/.bashrc as would be the case in other Linux based OS's but in /etc/paths.

/etc/paths is read-only so you'll need the sudo command to save any edits :

sudo vi /etc/paths

Note: vi is a sample file editor found in Mac OS X but others, like pico or emacs can be used as well.

The PATH variable below should reflect the path for PostgreSQL's bin/ directory, which is defaulted to /Library/PostgreSQL/9.1/bin. Change this to reflect your PostgreSQL installation path if you have a custom installation.
Add the following line to the top of the file:

/Library/PostgreSQL/9.1/bin

(If you've installed a version of PostgreSQL other than 9.1, change the version number in the path above accordingly.)

Opening a new Terminal.app window and typing env will show a list of all environmental variables.

Configure your tenant

The settings file for a tenant is located at either:

$CSPACE_JEESERVER_HOME/lib/tenants/{tenantname}/settings.xml, where {tenantname} is replaced by the actual name of the tenant;
or
$CSPACE_JEESERVER_HOME/lib/tenants/{tenantname}/local-{tenantname}-settings.xml, where {tenantname} is replaced by the actual name of the tenant.

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 zxvf v

Unknown macro: {multi-excerpt-include}

.tar.gz
mv

Unknown macro: {multi-excerpt-include}

application
rm v

Unknown macro: {multi-excerpt-include}

.tar.gz
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 Mac OS X 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 zxvf v

Unknown macro: {multi-excerpt-include}

.tar.gz
mv

Unknown macro: {multi-excerpt-include}

services
rm v

Unknown macro: {multi-excerpt-include}

.tar.gz
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-include}

Browser not supported