Creating your new tenant
Version 5
This document is being updated for CollectionSpace 5/6. The information is accurate, 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.
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:
- 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 Imagewalkerart
for the Walker Art Centerpahma
for the Phoebe A. Hearst Museum of Anthropologyucjeps
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 Imagewalkerart.org
for the Walker Art Centerhearstmuseum.berkeley.edu
for the Phoebe A. Hearst Museum of Anthropologyucjeps.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 profiles 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 |
Botanical Garden | botgarden |
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 system, and are intended to run in a terminal shell like bash or sh.
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.
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
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:
- In the Email field of the Sign In screen, enter
, whereadmin@
{internet_domain
}{internet_domain
} is the Internet domain of your museum. For example, if your museum's Internet domain isdemo.example.org
, enter admin@demo.example.org. - In the Password field of the Sign In screen, enter
Administrator
, which is the default password for that user. - Click the Sign In button.
- In the Email field of the Sign In screen, enter
- 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/{
(where tenant_short_name
}/tenant-bindings.merged.xml{
} represents the short name of the tenant).tenant_short_name
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.