Installing on Ubuntu LTS

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 collectionspace for the account:

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

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

echo -e "ExamplePassword\nExamplePassword" | sudo passwd collectionspace ### Replace 'ExamplePassword' 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.11) ...
Processing triggers for man-db (2.9.1-1) ...
Processing triggers for ca-certificates (20210119~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.2) ...
Processing triggers for libgdk-pixbuf2.0-0:amd64 (2.40.0+dfsg-3ubuntu0.2) ...

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

Installing CollectionSpace

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

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 collectionspace user (or sudo su - collectionspace) 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: Sun, 22 Aug 2021 05:37:36 GMT

<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns2:system_info_common xmlns:ns2="http://collectionspace.org/services/systeminfo"><displayName>CollectionSpace Services v7.0</displayName><instanceId>_default</instanceId><version><major>7</major><minor>0</minor><patch>0</patch><build>1</build></version><javaVersionString>1.8.0_292</javaVersionString><host>Architecture:amd64 Name:Linux Version:5.4.0-81-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 collectionspace 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
• Add Apache TLS/SSL reverse proxy to CollectionSpace
• Create a custom tenant to add your local configuration changes