Versions Compared

Old Version 14

changes.mady.by.user Ray Lee

Saved on

compared with

New Version Current

changes.mady.by.user Ray Lee

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

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 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 tenant/profile.  The "The core" profile  profile is a generic/general-purpose instance of CollectionSpace.  There are a handful of more 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.

Info
titleRECOMMENDED: 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  profile installed and running first.

...

Ideally, the Ubuntu server you're going to try to install CollectionSpace onto has been setupset up/created solely for the purpose of running CollectionSpace.  If 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 1820.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
     
Info

Last tested (possibly with an earlier CollectionSpace release) on:
20192020: Ubuntu 1820.04.3

Installation Prerequisites

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

...

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

Code Block
sudo useradd -c "CollectionSpace admin linux account" -m -s /bin/bash cspacecollectionspace

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

Code Block
echo -e "cspaceExamplePassword\ncspacenExamplePassword" | sudo passwd cspacecollectionspace ### Replace 'cspaceExamplePassword' with a strong password

Next, install the prerequisites available via the using apt manager:

Code Block
languagebash
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:

Code Block
SettingProcessing triggers upfor mavensystemd (3245.0.5-14-4ubuntu3.11) ...
update-alternatives: using /usr/share/maven/bin/mvn to provide /usr/bin/mvn (mvn)
in auto mode
Processing triggers for libcman-bindb (2.19-0ubuntu6.79.1-1) ...
Processing triggers for libgdk-pixbuf2.0-0:amd64 (2.30.7-0ubuntu1.2) ...
Processing triggers for ca-certificates (20141019ubuntu0.14ca-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.

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

Multiexcerpt include macro
namePOSTGRESQL LINUX
pagePostgreSQL Installation under Linux

Installing CollectionSpace

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

Multiexcerpt macro
nameSETUPTOMCAT

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:

bash

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

bash

Unpack the tarball:

bash

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

Next, make necessary files owned by the cspace user:

bashYou can remove the tarball if you want/need:

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

Multiexcerpt include macro
namePOSTGRESQL LINUX
pagePostgreSQL Installation under Linux

Installing CollectionSpace

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


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
Multiexcerpt macro
nameSETUPENVIRONMENTVARIABLES
SETUPTOMCAT

Set up Tomcat

Log in to your Ubuntu server using an account with sudo privileges. Go to the directory where you want to install CollectionSpace. We recommend /opt/collectionspace.

bash

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

bash

Unpack the tarball:

bash

This will create an apache-tomcat-8.5.51

directory that was created when you unpacked the CollectionSpace tarball; example, "/usr/local/share/apache-tomcat-8.5.51"
  • CATALINA_HOME: The full path to the apache-tomcat-8.5.51 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

     directory in /opt/collectionspace.

    Next, make necessary files owned by the collectionspace user:

    bash

    You can remove the tarball if you want/need:



    Multiexcerpt macro
    nameSETUPENVIRONMENTVARIABLES

    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 collectionspace user account. Ensure that the following values exist in the collectionspace user's shell environment. In the next paragraph, we provide instructions for setting these environment variables automatically when you log in as the collectionspace user.

    • CSPACE_JEESERVER_HOME: The full path to your Java directory. If you are unsure where this variable should point to, you can execute this command:bash

      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_MATERIALSthe apache-tomcat-8.5.51 directory that was created when you unpacked the CollectionSpace tarball; example, /opt/collectionspace/apache-tomcat-8.5.51
    • CATALINA_HOME: The full path to the apache-tomcat-8.5.51 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:

      bash

      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 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 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 Materials core/common tenant.
    • CSPACE_PUBLICARTANTHRO_CREATE_DISABLED_OPT: Default value is true. If set to false, enables the Public Art Anthropology tenant.
    • CSPACE_ANTHROBONSAI_CREATE_DISABLED_OPT: Default value is true. If set to false, enables the Anthropology Bonsai 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:

    Now edit the .bashrc file:

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

    bashtrue

    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.

    WARNING: Use difficult to guess values for the password environment variables above -i.e., the ones ending with "_PASSWORD". The value for the environment
    • 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.

    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 collectionspace user, edit ~/.bashrc (or ~/.bash_profile) and be sure to substitute the actual values for that are specific to your environment. Login as the collectionspace user:

    Now edit the .bashrc file:

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

    bashtrue

    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 collectionspace account, these environment variables will be set automatically.

    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. The source code resides in two projects hosted on GitHub: services, and application.  Logged in as the cspace user collectionspace user, enter the following commands:

    ...

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

    Code Block
    languagebash
    $CSPACE_JEESERVER_HOME/bin/startup.sh

    ...

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

    Code Block
    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:

    ...

    that the CollectionSpace server started up without problems.  Try the following command:

    Code Block
    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:

    Code Block
    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.

    ...

    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.

    ...

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

    ...

    Now that you have a working system you may want to