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. 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 https://collectionspace.org/community-profiles/ for details.
RECOMMENDED: Get the default profile working first
Selecting a Host Server/Machine for CollectionSpace
Ideally, the Ubuntu server on which you're going to install CollectionSpace has been 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.
There are a few options to create a new Ubuntu 22.04 LTS server solely for running CollectionSpace:
- VirtualBox can be used to create an Ubuntu server capable of running CollectionSpace.
- 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 on:
2024: Ubuntu 22.04
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 the name collectionspace
for the account:
sudo useradd -c "CollectionSpace admin 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 exiftool openjdk-8-jdk wget git
If all went well, you should see a message like:
Setting up openjdk-8-jre:arm64 (8u402-ga-2ubuntu1~22.04) ... update-alternatives: using /usr/lib/jvm/java-8-openjdk-arm64/jre/bin/policytool to provide /usr/bin/policytool (policytool) in auto mode Setting up humanity-icon-theme (0.6.16) ... Setting up libgail18:arm64 (2.24.33-2ubuntu2) ... Setting up libgtk2.0-bin (2.24.33-2ubuntu2) ... Setting up openjdk-8-jdk:arm64 (8u402-ga-2ubuntu1~22.04) ... update-alternatives: using /usr/lib/jvm/java-8-openjdk-arm64/bin/appletviewer to provide /usr/bin/appletviewer (appletviewer) in auto mode update-alternatives: using /usr/lib/jvm/java-8-openjdk-arm64/bin/jconsole to provide /usr/bin/jconsole (jconsole) in auto mode Setting up libgail-common:arm64 (2.24.33-2ubuntu2) ... Setting up ubuntu-mono (20.10-0ubuntu2) ... Processing triggers for libc-bin (2.35-0ubuntu3.6) ... Processing triggers for ca-certificates (20230311ubuntu0.22.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 libgdk-pixbuf-2.0-0:arm64 (2.42.8+dfsg-1ubuntu0.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
Instructions based on the Postgresql wiki After installing the PostgreSQL server, a system user named In your Linux shell, change/switch to this user: Next, edit the PostgreSQL So, in Ubuntu 22.04, for example, open it up with your preferred text editor: Towards the end of the file, add (or modify) the following lines of text to the section starting with something like "# IPv4 local connections:": Next, make sure entries under "IPv6 local connections" are disabled by adding the '#' character to beginning of this line: Save the changes and quit your editor. Finally, set the So, in Ubuntu 22.04, for example, open it with your favorite text editor then make the following changes to that file: The A Lowering this setting to 32 should also be fine, but you might need to adjust based on your system. Save your changes and quit. Log out of the ' Now we need to create some datatype casts that CollectionSpace uses. While logged in as the then enter the following commands into the Remain in the At In response, you should see a message similar to this: Enter the following command to create a In response, you should see a message similar to this: Quit the Log out of the ' Verify that you are able to connect to the PostgreSQL server using the If successful, you should be in the psql shell and see something like this: 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 by typing You're finished with the PostgreSQL setup. echo # Set up 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-12 postgresql-contrib-12
Setting up the PostgreSQL Server
Changes to PostgreSQL Configuration Files
postgres
should have automatically been created.sudo su - postgres
Changes to pg_hba.conf File
pg_hba.conf
configuration file using a tool like vi or vim. The location differs between Linux flavors, e.g.:/etc/postgresql/12/main/pg_hba.conf
vim /etc/postgresql/12/main/pg_hba.conf
# IPv4 local connections:
host all all samehost md5
# IPv6 local connections:
#host all all ::1/128 md5
Changes to postgresql.conf File
max_prepared_transactions
property in the main PostgreSQL config file named postgresql.conf
. The file's location differs between Linux flavors, e.g.:/etc/postgresql/12/main/postgresql.conf
vim /etc/postgresql/12/main/postgresql.conf
max_prepared_transactions = 64
max_prepared_transactions
property might be commented out with the '#
' character. If you see the '#
' character at the beginning of this line, remove it.max_prepared_transactions
variable setting of 64 might be too memory consuming for your system. If this value is indeed too high for your system, you'll get an error when restarting the PostgreSQL server. Something like:Restarting PostgreSQL 12 database server: main The PostgreSQL server failed to start. Please check the log output ... FATAL: could not create shared memory segment: Invalid argument
...
failed!
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'
postgres
user, enter the psql
shell:sudo su - postgres
psql -U postgres -d template1
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';
psql
shell and continue to the next section.Create the
csadmin
Userpsql
'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
You are now connected to database "postgres" as user "postgres".
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;
CREATE ROLE
psql
program by typing \q
(or press ctrl+d)
.postgres
' Linux account (the 'exit' command returns you to your normal linux account) and then restart the PostgreSQL server:exit
sudo systemctl restart postgresql
csadmin
account username and password you just added:psql -U csadmin -h localhost -d postgres
psql (12.18 (Ubuntu 12.18-1.pgdg22.04+1))
SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, bits: 256, compression: off)
Type "help" for help.
postgres=#
\q
(or press ctrl+d)
.
Installing CollectionSpace
Once all prerequisites have been installed and satisfied, you can begin installing the CollectionSpace server. Login to your Ubuntu server using an account with 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": Unpack the tarball: This will create an Next, make necessary files owned by the You can remove the tarball if you want/need: For the CollectionSpace server to install and run properly, it requires the following shell environment variables to be defined for the JAVA_HOME: The full path to your Java 8 directory. By default, all but the " CSPACE_BONSAI_CREATE_DISABLED_OPT: Default value is 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 set up 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., 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 The example below is for a Linux Bash shell. As the Now edit the Add the following lines of text to the end of the .bashrc file: 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 WARNING: Use difficult to guess values for the password environment variables above -i.e., the ones ending with " 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 You should see the following output: Next, let's build and deploy CollectionSpace from its source code. If successful, enter these commands: Change back to the services directory, and redeploy the application. Finally, create the CollectionSpace databases and a default set of users and permissions.Set up Tomcat
sudo
privileges. Go to the directory where you want to install CollectionSpace. We recommend /opt/collectionspace
:cd /opt
sudo mkdir collectionspace
cd collectionspace
sudo wget https://s3-us-west-2.amazonaws.com/cs-public-shared-files/releases/8.0/cspace-server-8.0.tar.gz
sudo tar -xzvof cspace-server-8.0.tar.gz
apache-tomcat-
directory in 8.5.51
/opt/collectionspace
.collectionspace
user:sudo chown -R collectionspace:collectionspace .
sudo rm cspace-server-8.0.tar.gz
Setting the CollectionSpace Environment Variables
collectionspace
user account. Ensure that the following values correspond to the collectionspace
user's shell environment. In the next paragraph, we provide instructions for setting these environment variables automatically when you login as the collectionspace
user."/opt/collectionspace/apache-tomcat-8.5.51"
CSPACE_JEESERVER_HOME
.5432
_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.8180
core
" CollectionSpace tenants/profiles are disabled. You'll need to explicitly enable the tenants you want to use by setting environment variables for them.true
. If set to false
, enables the core/common tenant.true
. If set to false
, enables the Anthropology tenant.true
. If set to false
, enables the Bonsai tenant.true
. If set to false
, enables the Botanical Garden tenant.true
. If set to false
, enables the Fine and Contemporary Art tenant.true
. If set to false
, enables the Herbarium tenant.true
. If set to false
, enables the Local History and Material Culture tenant.true
. If set to false
, enables the Materials tenant.true
. If set to false
, enables the Public Art tenant.https://core.dev.collectionspace.org:8180/cspace-services/
true
if the "shared" CollectionSpace instance is running SSL/HTTS.collectionspace
user, edit ~/.bashrc (or ~/.bash_profile) and be sure to substitute the actual values for that are specific to your environment. Log in as the collectionspace
user:sudo su - collectionspace
.bashrc
file:vim ~/.bashrc
#
# Environment variables for the CollectionSpace server
#
export CSPACE_JEESERVER_HOME="/opt/collectionspace/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_ANTHRO_CREATE_DISABLED_OPT="true"
export CSPACE_BONSAI_CREATE_DISABLED_OPT="true"
export CSPACE_BOTGARDEN_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_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"
collectionspace
account, these environment variables will be set automatically.source ~/.bashrc
_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.collectionspace
user, enter the following commands:cd /opt/collectionspace
git clone https://github.com/collectionspace/services -b v8.0-branch
git clone https://github.com/collectionspace/application -b v8.2-branch
CSPACE_CORE_CREATE_DISABLED_OPT
environment variable is set to the value false
.env | grep CSPACE_CORE_CREATE_DISABLED_OPT
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.cd services
mvn clean install -DskipTests
cd ../application
mvn clean install -DskipTests
cd ../services
ant undeploy deploy
ant create_db import
Starting the CollectionSpace server
To start the CollectionSpace server, login to the host machine as the collectionspace
user (or sudo su -
) and run this command:collectionspace
$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 Vary: Origin Vary: Access-Control-Request-Method Vary: Access-Control-Request-Headers Set-Cookie: JSESSIONID=24D1AC4DA8CFDA0DE2D144C2D3971889; Path=/cspace-services; HttpOnly X-Content-Type-Options: nosniff X-XSS-Protection: 1; mode=block Cache-Control: no-cache, no-store, max-age=0, must-revalidate Pragma: no-cache Expires: 0 X-Frame-Options: DENY Content-Type: application/xml Content-Length: 580 Date: Tue, 19 Mar 2024 17:33:27 GMT <?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns2:system_info_common xmlns:ns2="http://collectionspace.org/services/systeminfo"><displayName>CollectionSpace Services v8.0</displayName><instanceId>_default</instanceId><version><major>8</major><minor>0</minor><patch>0-SNAPSHOT</patch><build>c049973</build></version><javaVersionString>1.8.0_402</javaVersionString><host>Architecture:aarch64 Name:Linux Version:6.5.13-orbstack-00122-g57b8027e2387</host><hostTimezone>UTC</hostTimezone><hostLocale>en-US</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://<hostname>:8180/
cspace/core/login
where <hostname> is the hostname or IP address of the machine where you installed CollectionSpace. If you have a web browser running on the same server where you installed CollectionSpace, 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
Changing passwords of default users
Administrator and reader users are created when CollectionSpace is installed, with default passwords. These passwords must be changed to secure your system. Use the following instructions:
Next Steps
Now that you have a working system you may want to: