What to Expect

RECOMMENDED: Automated installer for CollectionSpace

We've created an Automated Installer for performing an unattended installation of CollectionSpace on selected Linux systems. Using the automated installer on a dedicated VPS or a VirtualBox server is the simplest and most reliable way to get a CollectionSpace instance installed and running.

This guide will help you manually install CollectionSpace on a Linux server running a recent Ubuntu LTS release. If you decide not to use the Automated Installer, you'll need to be very comfortable with the Linux bash shell and with using common Linux command-line tools to install and configure CollectionSpace. You will also need to have an account on the targeted Ubuntu server that has elevated (i.e., sudo) privileges/permissions.

After finishing the installation, you will have a fully functioning CollectionSpace instance that contains a working default "core" tenant/profile. The "core" profile is a generic/general-purpose instance of CollectionSpace. There are a handful of more domain-specific profiles that you can configure and use in CollectionSpace -see the demo site for more details at http://demo.collectionspace.org

RECOMMENDED: Get the default profile working first

The instructions on this page will help you install the core/default CollectionSpace profile. Before trying to select one of the domain-specific profiles or trying to customize your CollectionSpace instance, we strongly recommend getting the "core" profile installed and running first.

Selecting a Host Server/Machine for CollectionSpace

Ideally, the Ubuntu server you're going to try to install CollectionSpace onto has been setup/created solely for the purpose of running CollectionSpace. If the server is an existing system that is being used or has been used to host other software, you may encounter problems that will require advanced system administration and support.

If you want to create a new Ubuntu 16.04 LTS server solely for running CollectionSpace, here are a few options:

VirtualBox can be used to create an Ubuntu server capable of running CollectionSpace. See Using VirtualBox to Run CollectionSpace to learn more.
Linode.com provides cloud-based Ubuntu servers capable of running CollectionSpace for as little as $5-10/month (USD)
Amazon's AWS also provides cloud-based Ubuntu servers capable of running CollectionSpace

Last tested (possibly with an earlier CollectionSpace release) on:
March 14, 2018: Ubuntu 16.04

Installation Prerequisites

Before attempting to install CollectionSpace, please review the system requirements here: System Requirements for a CollectionSpace Server. First, login to your Ubuntu server and make sure you have sudo (super user) privileges. Try the following command:

sudo ls

You may be prompted for your password. If after entering your password, you don't encounter any errors then you're all set. If you do encounter errors and don't have sudo privileges, you cannot install CollectionSpace. Talk with your system administrator or learn how to grant yourself sudo privileges.

Next, create a system account for installing and managing CollectionSpace. Use name "cspace" to create the account:

sudo useradd -c "CollectionSpace admin linux account" -m -s /bin/bash cspace

Next, set a password for the new "cspace" account. Do NOT use the following example password. Create your own password and record it somewhere secure:

echo -e "cspace\ncspace" | sudo passwd cspace ### Replace 'cspace' with a strong password

Next, install the prerequisites available via the apt manager:

sudo apt-get update
sudo apt-get install ant maven imagemagick openjdk-8-jdk wget git

If all went well, you should see a message something like:

Setting up maven (3.0.5-1) ...
update-alternatives: using /usr/share/maven/bin/mvn to provide /usr/bin/mvn (mvn) in auto mode
Processing triggers for libc-bin (2.19-0ubuntu6.7) ...
Processing triggers for libgdk-pixbuf2.0-0:amd64 (2.30.7-0ubuntu1.2) ...
Processing triggers for ca-certificates (20141019ubuntu0.14.04.1) ...
Updating certificates in /etc/ssl/certs... 0 added, 0 removed; done.
Running hooks in /etc/ca-certificates/update.d....
done.

If you think you've encountered an error, send an email to the CollectionSpace "Talk" list at talk@collectionspace.org. Include any error messages you've seen and give a detailed description of what steps you've already performed.

Installing and Configuring the PostgreSQL Database Server

The excerpt 'postgres-ubuntu' was not found in the space 'CSPACE50' or you may not have the necessary permissions to access it.

If you're experiencing issues please see our Troubleshooting Guide.

If you think you've encountered an error, send an email to the CollectionSpace "Talk" list at talk@collectionspace.org. Include any error messages you've seen and give a detailed description of what steps you've already performed.

The excerpt 'postgresql-setup' was not found in the space 'CSPACE50' or you may not have the necessary permissions to access it.

If you're experiencing issues please see our Troubleshooting Guide.

If you think you've encountered an error, send an email to the CollectionSpace "Talk" list at talk@collectionspace.org. Include any error messages you've seen and give a detailed description of what steps you've already performed.

Installing CollectionSpace

Once all prerequisites have been installed and satisfied, you can begin installing the CollectionSpace server.

Setup Tomcat

Login to your Ubuntu server using an account with sudo privileges. Go to the directory where you want to install CollectionSpace. We recommend:

cd /usr/local/share

CollectionSpace runs as a Tomcat 7 server application. A pre-configured version of Tomcat 7 is provided with the CollectionSpace distribution package.

Start by downloading the CollectionSpace distribution package "tarball":

sudo wget ftp://nightly.collectionspace.org/pub/collectionspace/releases/5.0/cspace-server-5.0.tar.gz

Unpack the tarball:

sudo tar -xzvof cspace-server-5.0.tar.gz

This will create an apache-tomcat-7.0.64 directory in /usr/local/share.

Next, make necessary files owned by the cspace user and executable:

sudo chown -R cspace:cspace apache-tomcat-7.0.64/
sudo chmod u+x apache-tomcat-7.0.64/bin/*.sh

You can remove the tarball if you want/need:

sudo rm cspace-server-5.0.tar.gz

Setting the CollectionSpace Environment Variables

For the CollectionSpace server to install and run properly, it requires the following shell environment variables to be defined for the cspace user account. Ensure that the following values correspond to the cspace user's shell environment. In the next paragraph, we provide instructions for setting these environment variables automatically when you login as the cspace user.

CSPACE_JEESERVER_HOME: The full path to the apache-tomcat-7.0.64 directory that was created when you unpacked the CollectionSpace tarball; example, "/usr/local/share/apache-tomcat-7.0.64"
CATALINA_HOME: The full path to the apache-tomcat-7.0.64 directory, usually 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 example value for this variable in the next section is a Java Virtual Machine (JVM) memory setting.
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` | sed -e "s/\/jre\/bin\/java$//"
```
which gets you the path to the Java installation taking only the part that comes before the text "jre/bin/java". See the example values below.
DB_HOST: The hostname or IP address of the server running PostgreSQL. (Commonly 'localhost' when running on the same machine as catalina/tomcat)
DB_PORT: The port for the Postgresql servicer. Usually 5432
DB_CSADMIN_PASSWORD: The password for the administrative database user for the CollectionSpace application. This must match the password for the user that you specified while setting up PostgreSQL in the prerequisites section. (This administrative user by default will be named csadmin, and will be a postgresql 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 databases. Nuxeo is essentially 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 authentication and authorization.
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 databases.
CSPACE_INSTANCE_ID: String appended to default CollectionSpace database names. Use a value of "_default" by default. If your instance of CollectionSpace is sharing a PostgreSQL server with other CollectionSpace instances, this environment variable provides a way to distinguish your databases from others.
JEE_PORT: The HTTP port for the Services layer. Usually 8180
ANT_OPTS: Environment options for the Apache Ant build tool. The recommended options below are Java Virtual Machine (JVM) memory settings.
MAVEN_OPTS: Environment options for the Maven build tool. The recommended options below are Java Virtual Machine (JVM) memory settings.

By default, all but the "core" CollectionSpace tenants/profiles are disabled. You'll need to explicitly enable the tenants you want to use by setting environment variables for them.

CSPACE_CORE_CREATE_DISABLED_OPT: Default value is true. If set to false, enables the core/common tenant.
CSPACE_BONSAI_CREATE_DISABLED_OPT: Default value is true. If set to false, enables the Bonsai tenant.
CSPACE_FCART_CREATE_DISABLED_OPT: Default value is true. If set to false, enables the Fine and Contemporary Art tenant.
CSPACE_HERBARIUM_CREATE_DISABLED_OPT: Default value is true. If set to false, enables the Herbarium tenant.
CSPACE_LHMC_CREATE_DISABLED_OPT: Default value is true. If set to false, enables the Local History and Material Culture tenant.
CSPACE_MATERIALS_CREATE_DISABLED_OPT: Default value is true. If set to false, enables the Materials tenant.
CSPACE_PUBLICART_CREATE_DISABLED_OPT: Default value is true. If set to false, enables the Public Art tenant.
CSPACE_ANTHRO_CREATE_DISABLED_OPT: Default value is true. If set to false, enables the Anthropology tenant.
CSPACE_BOTGARDEN_CREATE_DISABLED_OPT: Default value is true. If set to false, enables the Botanical Garden tenant.

Your CollectionSpace instance can be configured to fetch data from another CollectionSpace instance. For example, the Materials profile/tenant can be configured to fetch shared authority and vocabulary data from a CollectionSpace instance that is setup to share common authority data. The following environment variables can used to create a connection to that CollectionSpace instance.

CSPACE_CLIENT_SAS_URL_OPT: The URL to the "shared" CollectionSpace instance -e.g., http://nightly.collectionspace.org:8180/cspace-services/
CSPACE_CLIENT_SAS_USER_OPT: A username for an account on the "shared" CollectionSpace instance.
CSPACE_CLIENT_SAS_PASSWORD_OPT: The password for the account on the "shared" CollectionSpace instance.
CSPACE_CLIENT_SAS_SSL_OPT: Set to true if the "shared" CollectionSpace instance is running SSL/HTTS.

The example below is for a Linux Bash shell. As the cspace user, edit ~/.bashrc (or ~/.bash_profile) and be sure to substitute the actual values for that are specific to your environment. Login as the cspace user:

sudo su - cspace

Now edit the .bashrc file:

vim ~/.bashrc

Add the following lines of text to the end of the .bashrc file:

#
# Environment variables for the CollectionSpace server
#
export CSPACE_JEESERVER_HOME="/usr/local/share/apache-tomcat-7.0.64"
export CATALINA_HOME="$CSPACE_JEESERVER_HOME"
export CATALINA_PID="$CSPACE_JEESERVER_HOME/bin/tomcat.pid"
export CATALINA_OPTS="-Xmx1524m"
export JAVA_HOME="/usr/lib/jvm/java-8-openjdk-amd64/"
export ANT_OPTS="-Xmx1524m"
export MAVEN_OPTS="-Xmx1524m"
export CSPACE_INSTANCE_ID="_default"
export DB_HOST="localhost"
export DB_PORT="5432"
export JEE_PORT="8180"
#
# PostgreSQL password for the special "csadmin" user/role we setup during the PostgreSQL installation
# Make sure you're using the correct value for the password -i.e., the one you picked/set during installation.
#
export DB_CSADMIN_PASSWORD="csadmin"
#
# Additional passwords for CollectionSpace's databases.  Change these passwords to something more secure and difficult to guess.
#
export DB_NUXEO_PASSWORD="nuxeo"
export DB_CSPACE_PASSWORD="cspace"
export DB_READER_PASSWORD="reader"
#
# Enable/Disable Tenants/Profiles.  A value of "true" will disable and "false" will enable.
#
export CSPACE_CORE_CREATE_DISABLED_OPT="false"
export CSPACE_BONSAI_CREATE_DISABLED_OPT="true"
export CSPACE_FCART_CREATE_DISABLED_OPT="true"
export CSPACE_HERBARIUM_CREATE_DISABLED_OPT="true"
export CSPACE_LHMC_CREATE_DISABLED_OPT="true"
export CSPACE_MATERIALS_CREATE_DISABLED_OPT="false"
export CSPACE_PUBLICART_CREATE_DISABLED_OPT="true"
export CSPACE_ANTHRO_CREATE_DISABLED_OPT="true"
export CSPACE_BOTGARDEN_CREATE_DISABLED_OPT="true"
export CSPACE_TESTSCI_CREATE_DISABLED_OPT="false"
#
# These are just example values for the Shared/Remote CollectionSpace connection information
#
export CSPACE_CLIENT_SAS_URL_OPT="http://nightly.collectionspace.org:8180/cspace-services/"
export CSPACE_CLIENT_SAS_USER_OPT="admin@materials.collectionspace.org"
export CSPACE_CLIENT_SAS_PASSWORD_OPT="Administrator"
export CSPACE_CLIENT_SAS_SSL_OPT="true"

Save your changes and exit the vim editor. Next, make sure to source your ~/.bashrc so the environment variables are set and available. The next time you login to the cspace account, these environment variables will be set automatically.

source ~/.bashrc

WARNING: Use difficult to guess values for the password environment variables above -i.e., the ones ending with "_PASSWORD". The value for the environment variable DB_CSADMIN_PASSWORD should be the password you created when you setup PostgreSQL in a previous section of this installation guide.

Now that we have the environment set up, we can grab the source-code for CollectionSpace. CollectionSpace consists of three distinct layers, which each run inside the Tomcat web server: the Services layer, the Application layer, and the UI layer. Logged in as the cspace user, enter the following commands:

cd $HOME
mkdir collectionspace-source
cd collectionspace-source
git clone https://github.com/collectionspace/services -b v5.0-branch
git clone https://github.com/collectionspace/application -b v5.0-branch

Before running the next set of commands, ensure that your tenant will be enabled by checking the corresponding environment variable. For example, to ensure the "core" tenant is enabled, verify that the CSPACE_CORE_CREATE_DISABLED_OPT environment variable is set to the value false.

env | grep CSPACE_CORE_CREATE_DISABLED_OPT

You should see the following output: CSPACE_CORE_CREATE_DISABLED_OPT=false. If you don't, return to the "Setting the CollectionSpace Environment Variables" section of this document and follow the instructions for enabling/disabling a tenant.

Next, let's build and deploy CollectionSpace from its source code.

cd services
mvn clean install -DskipTests

If successful, enter these commands:

cd ../application
mvn clean install -DskipTests

Next, lets run the commands to create the CollectionSpace databases and a default set of users and permissions.

The ant create_db -Drecreate_db=true portion of the below commands attempts to delete all existing CollectionSpace-related databases and replace them with new empty databases. If you have existing CollectionSpace databases that you don't want deleted, be sure to first rename them or back them up before running that command.

cd ~/collectionspace-source/services
ant undeploy deploy create_db -Drecreate_db=true import

And that's it. If all went well, CollectionSpace is now installed and ready to launch/start.

Enabling access logging (optional)

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. Follow these instructions to turn on access logging.

Starting the CollectionSpace server

To start the CollectionSpace server, login to the host machine as the cspace user (or sudo su - cspace) and run this command:

$CSPACE_JEESERVER_HOME/bin/startup.sh

Wait for it to fully start up, which might take 2-3 minutes the first time. (For more information on verifying server startup, see Starting Up CollectionSpace Servers.)

Testing to see if the installation was successful

To see if the installation was successful and that the CollectionSpace server started up without problems. Try the following command:

curl -i http://localhost:8180/cspace-services/collectionobjects -u admin@core.collectionspace.org:Administrator

If successful, you should see output that looks something like this:

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Set-Cookie: JSESSIONID=745CD7316C77FF98D2474C0640009FDD; Path=/cspace-services/; HttpOnly
Content-Type: application/xml
Content-Length: 383
Date: Wed, 20 Jul 2016 22:24:00 GMT

If you dont see "HTTP/1.1 200 OK" in the first line of the output, review the installation instructions to see if you missed a step. If you are not able to get passed this error, contact the CollectionSpace community "Talk" list at talk@collectionspace.org. Please include as much detail as possible so someone in the community can try to help you.

Logging in to the CollectionSpace landing page

Now that your CollectionSpace server is running, open a browser and go to http://<ip-address>:8180/cspace/core/login where <ip-address> is the hostname or IP address of the machine where you installed CollectionSpace. If you have a web browser running on the same server that you installed CollectionSpace on, you should be able to use this URL: http://localhost:8180/cspace/core/login

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

You now have a fully functioning CollectionSpace installation with two tenants for you to explore. You can get to each of them with:

The default/core tenant - http://<ip-address>:8180/cspace/core/login
A test tenant - http://<ip-address>:8180/cspace/test/login

Shutting down the CollectionSpace server

To properly shutdown the CollectionSpace, login to the host machine as the cspace user and enter this command:

$CSPACE_JEESERVER_HOME/bin/shutdown.sh

Next Steps

Now that you have a working system you may want to

Optional - Populate tenants with some sample data to get a better feeling for CollectionSpace in use.
Create a custom tenant to add your local configuration changes
Installing a default set of Reports into the "Core" tenant.

Browser not supported