What to Expect

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 comfortable with the Linux bash shell and with using common Linux command-line tools. 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 additional domain-specific profiles that you can configure and use in CollectionSpace – see the demo site for more details at http://demo.collectionspace.org.

Selecting a Host Server/Machine for CollectionSpace

Ideally, the Ubuntu server you're going to try to install CollectionSpace onto has been set up/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 20.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
   

Installation Prerequisites

Before attempting to install CollectionSpace, please review the System Requirements for a CollectionSpace Server. First, log in 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" for 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 using apt:

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

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

Processing triggers for systemd (245.4-4ubuntu3.2) ...
Processing triggers for man-db (2.9.1-1) ...
Processing triggers for ca-certificates (20201027ubuntu0.20.04.1) ...
Updating certificates in /etc/ssl/certs...
0 added, 0 removed; done.
Running hooks in /etc/ca-certificates/update.d...

done.
done.
Processing triggers for mime-support (3.64ubuntu1) ...
Processing triggers for libc-bin (2.31-0ubuntu9.1) ...
Processing triggers for libgdk-pixbuf2.0-0:amd64 (2.40.0+dfsg-3) ...

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

Instructions based on the Postgresql wiki

echo # Setup the postgres repository
sudo sh -c 'echo "deb http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'

echo # Install the postgres repository certificates
sudo apt install curl ca-certificates gnupg
curl https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -

echo # Install postgres
sudo apt update
sudo apt install postgresql-9.6 postgresql-contrib-9.6

Setting up the PostgreSQL Server

Changes to PostgreSQL Configuration Files

After installing the PostgreSQL server, a system user named "postgres" should have automatically been created.

In your Linux shell, change/switch to this user:

sudo su - postgres

Changes to pg_hba.conf File

Next, edit the PostgreSQL pg_hba.conf configuration file using a tool like vi or vim. The location differs between Linux flavors, e.g.:

• Debian/Ubuntu: /etc/postgresql/9.6/main/pg_hba.conf

So, in Ubuntu 16.04, for example, open it up with your preferred text editor:

vim /etc/postgresql/9.6/main/pg_hba.conf

Towards the end of the file, add (or modify) the following lines of text to the section starting with a line something like "# IPv4 local connections:":

# IPv4 local connections:
host    all             all         samehost                md5

Next, make sure entries under "IPv6 local connections" are disabled by adding the '#' character to beginning of this line:

# IPv6 local connections:
#host    all             all             ::1/128                md5

Save the changes and quit your editor.

Changes to postgresql.conf File

Finally, set the "max_prepared_transactions" property in the main PostgreSQL config file named postgresql.conf. The file's location differs between Linux flavors, e.g.:

• Debian/Ubuntu: /etc/postgresql/9.6/main/postgresql.conf

So, in Ubuntu 16.04, for example, open it up with your favorite text editor

vim /etc/postgresql/9.6/main/postgresql.conf

then make the following changes to that file:

max_prepared_transactions = 64

The max_prepared_transactions property might be commented out with the '#' character. If you see the '#' character at the beginning of this line, remove it.

Restarting PostgreSQL 9.6 database server: main The PostgreSQL server failed to start. Please check the log output ... FATAL: could not create shared memory segment: Invalid argument 
...
failed!

Save your changes and quit.

Logout of the 'postgres' account (use the shell 'exit' command to return to your normal linux account) and restart your PostgreSQL service:

exit
sudo systemctl restart postgresql

Set up datatype 'casts'

Now we need to create some datatype casts that CollectionSpace uses. While logged in as the postgres user, enter the psql shell:

sudo su - postgres
psql -U postgres -d template1

then enter the following commands into the psql shell:

CREATE FUNCTION pg_catalog.text(integer) RETURNS text STRICT IMMUTABLE LANGUAGE SQL AS 'SELECT textin(int4out($1));';
CREATE CAST (integer AS text) WITH FUNCTION pg_catalog.text(integer) AS IMPLICIT;
COMMENT ON FUNCTION pg_catalog.text(integer) IS 'convert integer to text';
CREATE FUNCTION pg_catalog.text(bigint) RETURNS text STRICT IMMUTABLE LANGUAGE SQL AS 'SELECT textin(int8out($1));';
CREATE CAST (bigint AS text) WITH FUNCTION pg_catalog.text(bigint) AS IMPLICIT;
COMMENT ON FUNCTION pg_catalog.text(bigint) IS 'convert bigint to text';

Remain in the psql shell and continue to the next section.

Create the 'csadmin' User

At psql's command prompt (ending in #), switch to the postgres database from the template1 database by entering the following (starting with a backslash character as shown):

\c postgres

In response, you should see a message similar to this:  You are now connected to database "postgres" as user "postgres".

 Enter the following command to create a csadmin user/role with appropriate privileges.  (Be sure to substitute a password of your choosing for replacemewithyourpassword below:

CREATE ROLE csadmin LOGIN PASSWORD 'replacemewithyourpassword' SUPERUSER INHERIT NOCREATEDB NOCREATEROLE NOREPLICATION;

In response, you should see a message similar to this: CREATE ROLE 

Quit the psql program by typing \q (or press ctrl+d).

Logout of the 'postgres' Linux account (use 'exit' command returns you to your normal linux account) and then restart the PostgreSQL server:

exit
sudo systemctl restart postgresql

Verify that you are able to connect to the PostgreSQL server using the csadmin account username and password you just added:

psql -U csadmin -h localhost -d postgres

If successful, you should be in the psql shell and see something like this:

psql (9.6.19)
SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, bits: 256, compression: off)
Type "help" for help.

postgres=# 

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.

Next, exit the psql shell:

\q

You're finished with the PostgreSQL setup. 

Installing CollectionSpace

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

Set up 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 8 server application. A pre-configured version of Tomcat 8 is provided with the CollectionSpace distribution package.

Start by downloading the CollectionSpace distribution package "tarball":

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

Unpack the tarball:

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

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

Next, make necessary files owned by the cspace user:

sudo chown -R cspace:cspace apache-tomcat-8.5.51

You can remove the tarball if you want/need:

sudo rm cspace-server-6.1.tar.gz

sudo su - cspace

vim ~/.bashrc

#
# Environment variables for the CollectionSpace server
#
export CSPACE_JEESERVER_HOME="/usr/local/share/apache-tomcat-8.5.51"
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="true"
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="true"
#
# 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"

source ~/.bashrc

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

env | grep CSPACE_CORE_CREATE_DISABLED_OPT

cd services
mvn clean install -DskipTests

cd ../application
mvn clean install -DskipTests

cd ~/collectionspace-source/services
ant undeploy deploy

ant create_db import

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 -u admin@core.collectionspace.org:Administrator http://localhost:8180/cspace-services/systeminfo

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

HTTP/1.1 200 
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-XSS-Protection: 1; mode=block
X-Frame-Options: DENY
X-Content-Type-Options: nosniff
Content-Type: application/xml
Content-Length: 541
Date: Fri, 30 Oct 2020 03:37:16 GMT

<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns2:system_info_common xmlns:ns2="http://collectionspace.org/services/systeminfo"><displayName>CollectionSpace Services v6.1</displayName><instanceId>_default</instanceId><version><major>6</major><minor>1</minor><patch>1</patch><build>1</build></version><javaVersionString>1.8.0_272</javaVersionString><host>Architecture:amd64 Name:Linux Version:5.4.0-52-generic</host><hostTimezone>UTC</hostTimezone><hostLocale>en</hostLocale><hostCharset>UTF-8</hostCharset></ns2:system_info_common>

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

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

• Change the passwords of the built-in administrator and reader users
• Create a custom tenant to add your local configuration changes