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.

{multi-excerpt:name=installing-xcode}

{note}
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)|http://dimitrisli.wordpress.com/2013/11/09/installing-homebrew-in-mac-os-x-10-9-mavericks/].
{note}

Tools for compiling and building source code aren't included by default on recent versions of Mac OS X. Apple's free [Xcode|http://developer.apple.com/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.
{multi-excerpt}

{multi-excerpt:name=installing-java7}
To install Java 7:
* Visit Oracle's [Java SE download page|http://www.oracle.com/technetwork/java/javase/downloads/index.html]
* 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?|http://www.java.com/en/download/help/mac_install.xml]:
** 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.)
{multi-excerpt}

ruby -e "$(curl -fsSL https://raw.github.com/mxcl/homebrew/go)"

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

brew install git

brew install libtool --universal

brew install imagemagick

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

brew install libtiff
brew install imagemagick --with-libtiff

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.

{multi-excerpt:name=getting-collectionspace}

h5. Getting CollectionSpace

Go to the directory where you want to install CollectionSpace:
{code}
cd /usr/local/share
{code}

Download the tarball via FTP:
{code}
ftp source.collectionspace.org
{code}
Log in with the username {{anonymous}} and any password.  Then:
{code-custom}
cd pub/collectionspace/releases/{multi-excerpt-include:pageTitle=VERSION INCLUSIONS|name=CSPACE-VERSION|nopanel=true}
get {multi-excerpt-include:pageTitle=VERSION INCLUSIONS|name=TARBALL-NAME|nopanel=true}
exit
{code-custom}

{tip:title=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 {code-custom}ftp://source.collectionspace.org/pub/collectionspace/releases/{multi-excerpt-include:pageTitle=VERSION INCLUSIONS|name=CSPACE-VERSION|nopanel=true}/{multi-excerpt-include:pageTitle=VERSION INCLUSIONS|name=TARBALL-NAME|nopanel=true}{code-custom}{tip}

{info}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'.)
{info}

Unpack tarball:
{code-custom}
tar zxvof {multi-excerpt-include:pageTitle=VERSION INCLUSIONS|name=TARBALL-NAME|nopanel=true}
{code-custom}

This will create an {multi-excerpt-include:pageTitle=VERSION INCLUSIONS|name=TOMCAT-VERSION|nopanel=true} directory.

{info}
Your account will need to have write permission to the newly-created {multi-excerpt-include:pageTitle=VERSION INCLUSIONS|name=TOMCAT-VERSION|nopanel=true} 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}}
{info}

Optionally remove the tarball:
{code-custom}
rm {multi-excerpt-include:pageTitle=VERSION INCLUSIONS|name=TARBALL-NAME|nopanel=true}
{code-custom}

Make necessary files executable:
{code-custom}
chmod u+x {multi-excerpt-include:pageTitle=VERSION INCLUSIONS|name=TOMCAT-VERSION|nopanel=true}/bin/*.sh
{code-custom}
{multi-excerpt}

{multi-excerpt:name=setting-everything-up}

h5. 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:title=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.
{tip}

*CSPACE_JEESERVER_HOME*: The full path to the {multi-excerpt-include:pageTitle=VERSION INCLUSIONS|name=TOMCAT-VERSION|nopanel=true} directory that was created when you unpacked the CollectionSpace tarball.
*CATALINA_HOME*: The full path to the {multi-excerpt-include:pageTitle=VERSION INCLUSIONS|name=TOMCAT-VERSION|nopanel=true} 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:
{code-custom}
export CSPACE_JEESERVER_HOME="/usr/local/share/{multi-excerpt-include:pageTitle=VERSION INCLUSIONS|name=TOMCAT-VERSION|nopanel=true}"
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"
{code-custom}

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:
{code}
. ~/.bashrc
{code}

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 :
{code}
sudo vi /etc/paths
{code}

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

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:
{code}
/Library/PostgreSQL/9.1/bin
{code}

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

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

{code-custom}
cd $HOME
mkdir collectionspace-source
cd collectionspace-source
wget https://github.com/collectionspace/application/archive/v{multi-excerpt-include:pageTitle=VERSION INCLUSIONS|name=CSPACE-VERSION|nopanel=true}.tar.gz
tar zxvf v{multi-excerpt-include:pageTitle=VERSION INCLUSIONS|name=CSPACE-VERSION|nopanel=true}.tar.gz
mv {multi-excerpt-include:pageTitle=VERSION INCLUSIONS|name=APPLICATION-TARBALL-EXPANDED-NAME|nopanel=true} application
rm v{multi-excerpt-include:pageTitle=VERSION INCLUSIONS|name=CSPACE-VERSION|nopanel=true}.tar.gz
cd application
{code-custom}

{warning}
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.
{warning}

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:

{code}
vi tomcat-main/src/main/resources/tenants/core/settings.xml
{code}

* 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:
{code}
<email>
    <baseurl>http://yourserverhostnamehere:8180</baseurl>
{code}

* 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.
{code}
    <from>youremail@example.com</from>
{code}

* 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:

{code-custom}
mvn clean install -DskipTests
{code-custom}

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

h3. Initialize database and users and permissions

{code-custom}
cd $HOME/collectionspace-source
wget https://github.com/collectionspace/services/archive/v{multi-excerpt-include:pageTitle=VERSION INCLUSIONS|name=CSPACE-VERSION|nopanel=true}.tar.gz
tar zxvf v{multi-excerpt-include:pageTitle=VERSION INCLUSIONS|name=CSPACE-VERSION|nopanel=true}.tar.gz
mv {multi-excerpt-include:pageTitle=VERSION INCLUSIONS|name=SERVICES-TARBALL-EXPANDED-NAME|nopanel=true} services
rm v{multi-excerpt-include:pageTitle=VERSION INCLUSIONS|name=CSPACE-VERSION|nopanel=true}.tar.gz
cd services
{code-custom}

* 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:
{code}
mvn clean install -DskipTests
{code}

* 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:title=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.
{warning}
{code}ant undeploy deploy create_db -Drecreate_db=true import{code}

{tip:title=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.
{tip}

You are now done with the most basic install.

h5. Starting the server

Start the server:
{code}
$CSPACE_JEESERVER_HOME/bin/startup.sh
{code}

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

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

{info}
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}}.
{info}
{multi-excerpt}

{multi-excerpt-include:pageTitle=Initializing data|name=authorities-and-vocabularies|nopanel=true}

{multi-excerpt-include:pageTitle=Initializing data|name=sample-data|nopanel=true}

{multi-excerpt-include:pageTitle=Enabling access logging|name=access-logging-benefits|nopanel=true}

{multi-excerpt-include:pageTitle=Enabling access logging|name=enabling-access-logging|nopanel=true}

{multi-excerpt-include:pageTitle=Installing 4.1 on Yum Compatible Linux Distributions|name=and-youre-done|nopanel=true}