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

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

Deploy (push) your new tenant in the Application layer to the CollectionSpace server

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

Services layer

Create and modify the Services 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 Services source code directly into that folder.
3. Make sure that the folder created by the checkout process is named services (If it isn't, rename that folder to services)

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

5. Inside the "services" folder, there is a sub-folder also named "services".  Copy the entire services/common/src/main/cspace/config/services/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. Recall that there is a second identically-named services folder just underneath the top-level services folder.)
   For instance, at a Terminal prompt in a Linux, Mac OS X, or other Unix-like system, you could enter:

   On many systems, you can simply select the folder, copy the folder, paste it into the same location, and rename it.

6. Inside the newly copied demo folder, rename the core-tenant-bindings.delta.xml file, to reflect the short name of your museum.
   For instance, at a Terminal prompt in a Linux, Mac OS X, or other Unix-like system, you could enter:

7. Open the file services/common/src/main/cspace/config/services/tenants/demo/demo-tenant-bindings.delta.xml in a text editor. (Substitute the actual short name of your museum for each instance of demo in this file path.) You'll need to make two changes to this file. 

   1. Enable the <tenant> element by removing the XML comment markers, <!– and –>, that directly surround it.

   2. Replace the value of the id="" attribute with the actual tenant ID for your museum. (You created that tenant ID when you configured your tenant in the Application layer.) For example, if your museum's tenant ID was 5, you would change: 

      to

8. Directly within the folder in which you've checked out the Services source code (i.e. the top-level "services" folder not the "services" sub-folder), at a Terminal or command prompt, you can now 'build' the Services layer. Enter:

   This command can take 10 minutes or more to complete its work. (Starting with CollectionSpace version 4.2, however, it has been significantly sped up.)

Deploy (push) your new tenant in the Services layer to the CollectionSpace server

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

   This command can take 10 minutes or more to complete its work.

   In part, this step will deploy (push) your new mymuseum folder for your tenant to the CollectionSpace server, in the location $CSPACE_JEESERVER_HOME/cspace/config/services/tenants/{mymuseum}.

Create user accounts, roles, and permissions

You'll next create two default user accounts within your new tenant:

• An 'admin' user that has all available privileges, including the rights to create additional users
• A 'reader' user that has only read privileges, allowing it to view - but not edit - data

along with a set of permissions that allow these users to log in and perform various actions.

To do so, at a Terminal or command prompt, enter:

Start the server

After performing the steps above:

1. Start the CollectionSpace server  .
2. Wait at least 1-2 minutes for the servers to start up.

Verify Your New Tenant

Initialize Authorities and Term Lists

As described in Initializing data, you'll next need to initialize authority and vocabulary terms in your new tenant:

• Make sure you are currently logged into your tenant (e.g. demo) as described above, then enter this URL in a new browser tab or window:
  http://<ip-address>:8180/collectionspace/tenant/demo/authorities/initialise

Next Steps

Troubleshooting

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

2. Verify that the following file exists: $CSPACE_JEESERVER_HOME/cspace/config/services/tenants/{mymuseum}/tenant-bindings.merged.xml (where {mymuseum} represents the actual short name of your museum).
   Explanation: when the cspace-services.war server for CollectionSpace's Services layer starts up, it will merge any tenant-specific configuration you've put into your 'delta' file, {mymuseum}-tenant-bindings.delta.xml with the full set of 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 same location, reflecting the results of this merge. If that file doesn't exist, that signifies that something may have gone wrong during the merge process, and hence that some configuration in that tenant bindings file might have

Summary

This document has explained how to create the files and folders for a new tenant, within which you can configure CollectionSpace for your museum.