Creating your new tenant

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.

Contents

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:

1. Click the Create New tab.
2. Under the Procedures heading, click on Group.
3. In the Title field, enter "My First Group".
4. 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:

1. In the search box at the top of the page, select Groups, and enter "first".
2. 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:

Procedure for creating a new tenant

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.

 # Change into the directory that contains your CollectionSpace source code.
# For example, if that directory is /opt/collectionspace, enter:
cd /opt/collectionspace
 
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

Deploy the configuration with the following command:

mvn clean install -DskipTests

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

[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  5.971 s
[INFO] Finished at: 2024-04-03T03:22:03Z
[INFO] ------------------------------------------------------------------------

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

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

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

2. 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.
3. 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.

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