Creating your new tenant

Task Description

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

Procedure for creating a new tenant

The easy way

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

In addition to picking the shortname and domain name as described above, you also need to select a new tenant ID,(an arbitrary integer not already used by another tenant), and existing tenant to copy. This example will show copying the core tenant, but if your collection consists of fine art of variable media, you might want to start from the fcart tenant instead.

Navigate to the directory containing the source directories for application, services and ui. Something like:

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

Now add in your values for the shortname, domain name, and tenant id of your new tenant, and the shortname of the tenant you want to clone.

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

Now run this command:

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

BUILD SUCCESS

Total time: 45.832s

We'll now do the same process for services and ui directories

The basic custom tenant configuration files have now been created and are ready to deploy. If you want details of what the new tenant config just created, read the section below, The less-easy way. Otherwise, you can skip ahead to the Deploy section below

If you've previously deployed and started your CollectionSpace instance, then you'll need to also run the following command to create the necessary AuthN/AuthZ information for your new tenant.

You're now ready to launch/start CollectionSpace.  Once started, you can login to your new tenant with a URL that looks something like this:

The less-easy way

Make a folder/directory to hold the source code for all three CollectionSpace layers: Services, Application, and UI

1. Make a new folder to contain the CollectionSpace source code for all three CollectionSpace layers. You might name it something like cspace or collectionspace or even cspace-source, for example.

User Interface (UI) layer Changes

Create and modify the UI layer files and folders for your new tenant

1. Change directories into the folder you previously created to hold the CollectionSpace source code.

2. Check out the UI source code directly into that folder.

3. Make sure that the folder created by the checkout process is named ui (If it isn't, rename that folder to ui)

4. Change directories into that newly-checked out ui folder.
   For instance, at a Terminal prompt in a Linux, Mac OS X, or other Unix-like system, you could enter:

5. Copy the entire src/main/webapp/tenants/core folder, with all of its contents, to a new folder named for your museum. This new folder should reside directly alongside the core folder. (That is, both folders should be contained within the same parent folder.)
   For instance, at a Terminal prompt in a Linux, Mac OS X, or other Unix-like system, you could enter:

6. Open the file src/main/webapp/tenants/mymuseum/bundle/core-messages.properties-overlay in a text editor.

   1. Using your editor's global search and replace tool, globally replace, using case-sensitive replacement, every instance of core with demo.

Deploy (push) your new tenant to the CollectionSpace server

Directly within the folder in which you've checked out the UI source code (i.e. not in a sub-folder), at a Terminal or command prompt, enter:

Application layer

Create and modify the Application layer files and folders for your new tenant

1. Change directories into the folder you previously created to hold the CollectionSpace source code.

2. Check out the Application source code directly into that folder.

3. Make sure that the folder created by the checkout process is named application (If it isn't, rename that folder to application)

4. Change directories into that newly-checked out application folder.
   For instance, at a Terminal prompt in a Linux, Mac OS X, or other Unix-like system, you could enter:

5. Copy the file tomcat-main/src/main/resources/core-tenant.xml to a new file renamed with your museum's short name.
   For instance, at a Terminal prompt in a Linux, Mac OS X, or other Unix-like system, you could enter:

6. Open the file tomcat-main/src/main/resources/{mymuseum}-tenant.xml in a text editor.

   1. Using your editor's global search and replace tool, globally replace, using case-sensitive replacement, every instance of core with demo.

7. Copy ("clone") the entire tenant folder for the core tenant, tomcat-main/src/main/resources/tenants/core with all of its contents, to a new folder in the same location, renamed to your museum's short name. This new folder should reside directly alongside the core folder. (That is, both folders should be contained within the same parent folder.)
   For instance, at a Terminal prompt in a Linux, Mac OS X, or other Unix-like system, you could enter:

8. Open the file tomcat-main/src/main/resources/tenants/demo/settings.xml in a text editor. 

   1. Using your editor's global search and replace tool, replace every instance of core.collectionspace.org with the Internet domain name of your museum; for example walkerart.org or ucjeps.berkeley.edu After making this change, here's an excerpt from what part of that file should now look like if, for example, your museum's Internet domain name were mymuseum.org:

   2. Using your editor's global search and replace tool, globally replace, using case-sensitive replacement:

      • Every instance of core with demo

      • Every instance of Core with Demo
        After making this change, here's an excerpt from what part of that file should now look like:

   3. Change the tenant ID (the value of the <tenant> element) from its current value to a new value, one not used by any other tenant in your CollectionSpace system. In the following example, the tenant ID for the demo tenant has been changed from its default value of 1 to a new value of 5:

   4. Make the identical change, in this example from 1 to 5, to the second instance of the tenant ID in that file (the value of the <id> element inside the <service>...<tenant> section):

9. Recommended: If you would like your museum's data to be stored in a separate database, rather than intermingled with that of other museum tenants in a common database, add a <name> element to the <repository> section, with its value set to your desired name for that separate database. (The value of that element must be a valid PostgreSQL database name; see the PostgreSQL documentation on valid identifiers for the current naming rules.)
   
   See Storing your museum's data in its own database for more information on this option.
   
   In the example below, a <name> element was added, with a value of mymuseum_domain. This will result in the creation of a database named mymuseum_domain, which will be used to store data for the mymuseum tenant:

10. Save your modified file, tomcat-main/src/main/resources/tenants/demo/settings.xml