Creating your new tenant

Prerequisites

Install and Start the CollectionSpace Server

Install a working CollectionSpace system. See Installing CollectionSpace.

If it is not already running, start the CollectionSpace server. See Starting up the CollectionSpace Server.

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. See Shutting 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 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:

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.

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

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.

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

Deploy the configuration with the following command:

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

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

Build and deploy the configuration with the following commands:

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

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

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.

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.