Version 5

This document is being updated for CollectionSpace 5. The information is accurate for version 5, but is incomplete where noted.

This document explains how to make a one-time change to create your tenant – the space or partition within which you'll make most of the configuration changes to adapt CollectionSpace for your museum.

You'll perform the following steps within each of CollectionSpace's three layers:

Create the files and folders for your new tenant.
Deploy (push) these files and folders to the appropriate folders on the CollectionSpace server.

Prerequisites

Install CollectionSpace

Install a working CollectionSpace system by completely following all of the steps described in the installation instructions for your operating system.

Start the CollectionSpace Server

Start the CollectionSpace server, if it is not already running.

Verify that your CollectionSpace installation is working

Verify that you can log in to the core tenant – a generic tenant that is installed with your CollectionSpace system – by visiting http://{hostname}:8180/cspace/core in a web browser, where {hostname} is the Internet hostname or IP address of your CollectionSpace system.

When the Sign in screen appears, follow the on-screen instructions to log in. Once you've logged in, verify that you can successfully save a record:

Click the Create New tab.
Under the Procedures heading, click on Group.
In the Title field, enter "My First Group".
Click Save. The message "Saved My First Group" should appear at the bottom of the page.

If the save succeeds, verify that you can search for this record:

In the search box at the top of the page, select Groups, and enter "first".
Press Enter, or click on the magnifying glass icon.

A list of matching Group records should now be displayed, containing the record you just created.

Shut down the CollectionSpace server

Shut down the CollectionSpace server.

Pick a short name for your museum

Choose a highly recognizable short name for your museum. You'll use this name in many places when creating your tenant. Some examples of short names chosen or considered by early CollectionSpace implementers:

mmi for the Museum of the Moving Image
walkerart for the Walker Art Center
pahma for the Phoebe A. Hearst Museum of Anthropology
ucjeps for the University and Jepson Herbaria, UC Berkeley

If you create more than one tenant, make sure the short name is different for each.

Pick an ID for your tenant

Choose an ID for your tenant. The ID should be an integer, and it should be between 100 and 199 (inclusive), to avoid clashing with the IDs of tenants that are installed with CollectionSpace. If you create more than one tenant, be sure to choose a different ID for each. The IDs of all tenants on your system must be unique.

Identify the Internet domain name of your museum

You'll also need to identify the Internet domain name of your museum. You'll use this in many places, as well, when creating your tenant. Some examples of Internet domain names associated with early CollectionSpace implementers:

movingimage.us for the Museum of the Moving Image
walkerart.org for the Walker Art Center
hearstmuseum.berkeley.edu for the Phoebe A. Hearst Museum of Anthropology
ucjeps.berkeley.edu for the University and Jepson Herbaria, UC Berkeley

If you create more than one tenant, make sure the domain name is different for each.

Select a profile/tenant to use as a template

CollectionSpace comes pre-configured with /wiki/spaces/COL/pages/675184645 for various museum domains and communities of practice. Before creating your tenant, you'll need to select a profile to use as a basis for further customization. Choose the profile that most closely matches the needs of your collection. If you're unsure of the profile to use, or your collection isn't covered by any of the existing profiles, use the common (core) profile. In terms of configuration, a profile is really just a tenant that is used as a template for creating your new tenant. You can also use any tenant that you've previously created as the template for your new tenant.

Whether you use one of the profile tenants or one of your own tenants, you'll need the short name of the tenant that you want to use as a template. The short names of the profile tenants that are installed with CollectionSpace are listed below:

Profile	Tenant Short Name
Common (Core)	core
Anthropology	anthro
Bonsai Garden	bonsai
Design Materials	materials
Fine and Contemporary Art	fcart
Local History and Material Culture	lhmc
Public Art	publicart

Procedure for creating a new tenant

The commands listed below, which perform various steps in the configuration process, are for a Linux, Mac OS X, or other Unix-like system, and are intended to run in a Terminal shell like bash or sh. If you're using a Windows system, you can use the comparable cmd or PowerShell commands, bash via Windows Subsystem for Linux, or a tool like cygwin.

You can also use a graphical desktop interface rather than the command-line operations to perform these same steps: navigating through folders, copying folders, renaming files and folders, and so on. Also, in places where you're instructed to edit files, you're welcome to use your favorite GUI editor.

If you used the automated installer to install CollectionSpace, the commands listed below should be run as the cspace user.

CollectionSpace provides a tool to quickly copy the configuration of an existing tenant to create a new one.

Navigate to the directory containing the source directories for application and services.

cd $HOME
 
# Change into the directory that contains your CollectionSpace source code.
# For example, if that directory is named "collectionspace-source", enter:
cd collectionspace-source
 
ls
> application   services

We are going to update the tenant.properties file with a few details.

cd application
vim tenant.properties

Fill in the values for template.tenant.shortname, tenant.shortname, tenant.id, and tenant.internet.domain with the short name of the tenant you're using as a template, the short name of your new tenant, the ID of your new tenant, and the Internet domain name of your tenant.

# Values in this 'tenant.properties' file will be used
# in targets in the Ant buildfile, build.xml, when copying
# ("cloning") a 'template tenant' to create a new tenant

# Values for these properties can instead, or also, be
# provided at the command line when invoking Ant, via
# one or more arguments similar to:
# -Dvariable.name=somevalue
#
# Where there are conflicts, values provided via the command line
# are used in preference to those provided in this properties file.

# The short name for the existing tenant that will be 
# copied ("cloned"), to create a new tenant
# example:  template.tenant.shortname=fcart
template.tenant.shortname=

# The short name for the new tenant to be created
# example: tenant.shortname=mymuseum
tenant.shortname=

# The ID for the new tenant to be created
# (an integer from 100 to 199)
# example: tenant.id=105
tenant.id=

# The internet domain for the new tenant to be created
# example: tenant.internet.domain=mymuseum.example.org
tenant.internet.domain=

Save that file and run the clone tool from the command line:

ant clone-tenant

CollectionSpace 5.1 and earlier: Because of a bug in the clone-tenant utility, you'll need to manually edit one of the configuration files. Open the file at application/tomcat-main/src/main/resources/{tenant_short_name}-tenant.xml. Change the content of the XML element <tenantid> to be the value you chose for your tenant ID (a number from 100-199).

Deploy the configuration with the following command:

mvn clean install -DskipTests

When complete, you should see a final message that looks something like:

BUILD SUCCESSFUL
Total time: 0s

We'll now do the same process for services directory.

# Copy the tenant.properties file we modified from the applications directory to the services directory.
cp tenant.properties ../services
cd ../services
ant clone-tenant

Build and deploy the configuration with the following commands:

mvn clean install -DskipTests
ant undeploy deploy

Run the following command to create the users, roles, and permissions for your new tenant.

ant import

CollectionSpace 5.1 and earlier: The clone-tenant utility does not yet fully support CollectionSpace 5, so some additional manual steps are required to deploy the user interface for your tenant. These steps are not needed in CollectionSpace 5.2 and above.

Change to the cspace-ui directory under services:

cd cspace-ui

Run the following command, replacing {TEMPLATE_SHORT_NAME} with the short name of the template tenant, in all uppercase letters. For example, CORE if you're cloning the common (core) profile tenant, PUBLICART if you're cloning the public art profile tenant.

CSPACE_{TEMPLATE_SHORT_NAME}_CREATE_DISABLED_OPT=false ant deploy

In the webapps directory in tomcat, a directory will now exist for the UI of the template tenant. Clone that directory for your new tenant. In the following commands, replace {template_short_name} with the short name of the template tenant, and {tenant_short_name} with the short name of your new tenant.

cd /usr/local/share/apache-tomcat-7.0.64/webapps
cp -r cspace#{template_short_name} cspace#{tenant_short_name}

In the newly cloned directory for your tenant, edit the index.html file. In the following commands, replace {tenant_short_name} with the short name of your new tenant.

cd cspace#{tenant_short_name}
vim index.html

The index.html file contains a <script> tag, in which various properties of the UI are set. Make the following changes: Set the tenantId property to the ID of your new tenant. Set the basename property to /cspace/{tenant_short_name}, replacing {tenant_short_name} with the short name of your new tenant. If your tenant ID is 199, and your tenant short name is demo, the relevant lines would look like:

tenantId: '199',

basename: '/cspace/demo',

You're now ready to start CollectionSpace. Once started, you can log in to your new tenant with a URL that looks like:

http://{hostname}:8180/cspace/{tenant_short_name}

Verify Your New Tenant

In a web browser, verify that you can log in to your tenant by visiting by visiting http://{hostname}:8180/cspace/{tenant_short_name} in a web browser, where {hostname} is the Internet hostname or IP address of your system, and {tenant_short_name} is the short name of your new tenant.
Log in as your new tenant's administrative user. This user can edit any records and has the ability to create other users, including users with more limited privileges:
1. In the Email field of the Sign In screen, enter admin{internet_domain}, where {internet_domain} is the Internet domain of your museum. For example, if your museum's Internet domain is demo.example.org, enter admin@demo.example.org.
2. In the Password field of the Sign In screen, enter Administrator, which is the default password for that user.\
3. Click the Sign In button.
Verify that you can create a record, and find it using search.

Next Steps

Change the passwords of the default administrator (admin@{internet_domain}) and reader (reader@{internet_domain}) accounts, using the instructions for changing the password of an immutable account.
Security

Your CollectionSpace installation is insecure until you change these passwords.

Instructions for the following steps are in progress.

Customize the login screen text for your tenant

Troubleshooting

Open the log file that is written to when the server starts up, $CSPACE_JEESERVER_HOME/logs/catalina.out, and check whether any serious error messages are present in that file. Those messages will typically appear somewhat near the end of that file, and may contain words like FATAL or Exception. They may also be followed by long lists ("stack traces") of code files and line numbers through which those errors propagated.
Verify that the following file exists: $CSPACE_JEESERVER_HOME/cspace/config/services/tenants/{tenant_short_name}/tenant-bindings.merged.xml (where {tenant_short_name} represents the short name of the tenant).
Explanation: when the cspace-services.war application for CollectionSpace services starts up, it will merge any tenant-specific configuration present in your 'delta' file, {tenant_short_name}-tenant-bindings.delta.xml with the default settings for a CollectionSpace tenant (which are stored in a "prototype" tenant bindings file). This will create a new tenant-bindings.merged.xml file in that location, reflecting the results of the merge. If that file doesn't exist, it signifies that something may have gone wrong during the merge process.

Additional troubleshooting steps can be added here, such as:

Verifying that rows pertaining to the newly-created tenant have been added to the relevant tables (users, tenants ...) in the cspace PostgreSQL database.
Verifying that the separate PostgreSQL database for your own museum exists.

Contents

Browser not supported