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

No preview available. Please publish the page first.

If you're experiencing issues please see our Troubleshooting Guide.

Procedure for creating a new tenant

The commands listed below, which perform various steps in the configuration process, are for a Linux, Mac OS X, or other Unix-like system, and are intended to run in a Terminal shell like bash or sh. If you're using a Windows system, you can use the comparable cmd or PowerShell commands, or a tool like cygwin.

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.

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

Because of a bug in the latest version of the clone-tenant utility, you'll need to manually edit one of the configuration files. Open the file at application\tomcat-main\src\main\resources\<your_tenant_short_name>-tenant.xml. Ensure the value of the XML element "<tenantid>" is equal to the value you chose for your tenant ID (some number).

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

Unknown macro: {multi-excerpt}

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

Change directories into the folder you previously created to hold the CollectionSpace source code.
Check out the UI source code directly into that folder.
Make sure that the folder created by the checkout process is named ui (If it isn't, rename that folder to ui)
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:
```
 
```
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:
```
 
```
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:

This will package up your new tenant, along with other UI-related files, into a cspace-ui.war file. That file will then be deployed (pushed) to the CollectionSpace server, in the location $CSPACE_JEESERVER_HOME/webapps.

If you were to peek inside that WAR file (for instance, via the command jar tvf $CSPACE_JEESERVER_HOME/webapps/cspace-ui.war), among the many files listed there you'd see your new tenant at tenants/{mymuseum}, where mymuseum is the actual short name of your museum.

Application layer

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

Change directories into the folder you previously created to hold the CollectionSpace source code.
Check out the Application source code directly into that folder.
Make sure that the folder created by the checkout process is named application (If it isn't, rename that folder to application)
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:
```
 
```
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:
```
 
```
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.
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:
```
 
```
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):
```
 
```
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:
```
 
```
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

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:
```
 
```

In part, this will deploy (push) the tenants/{mymuseum}/settings.xml file to the CollectionSpace server, in the location $CSPACE_JEESERVER_HOME/lib/tenants/demo. This will also deploy the demo-tenant.xml file to the location $CSPACE_JEESERVER_HOME/lib, renaming it to cspace-config-demo.xml.

Services layer

Unknown macro: {multi-excerpt}

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

Change directories into the folder you previously created to hold the CollectionSpace source code.
Check out the Services source code directly into that folder.
Make sure that the folder created by the checkout process is named services (If it isn't, rename that folder to services)
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:
```
 
```
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.
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:
```
 
```
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
```
 
```
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

Unknown macro: {multi-excerpt}

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:

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

Verify Your New Tenant

No preview available. Please publish the page first.

If you're experiencing issues please see our Troubleshooting Guide.

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

After logging in successfully, you should immediately change the password for your tenant's administrative user. Click the Administration tab, then the Users tab, to change this password.

Changing the password for your tenant's administrative user will also require a configuration change in a settings file in the Application layer. (That's why the admonition above about changing the Administrator password - while definitely a best practice - is elided above.) Instructions on doing so should be added here or in a separate document.

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/{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

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 (e.g. mymuseum_domain) exists ... if and only If during configuration, you specified the option to store your museum's data in a separate database of its very own, rather than intermingled with that of other museum tenants in a common database, that is.

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.

Advanced: Creating a new tenant on a different CollectionSpace server host

This tip presents an advanced topic and only applies to one - very specialized - situation.

The instructions above are intended to be performed on the same computer on which you are running a CollectionSpace system, and will take effect within that system.

If, however, you plan to push configuration changes for your museum from your computer to a second, different host computer - perhaps to a computer running a production CollectionSpace system, when your own computer is used for development, testing, or quality assurance - you have several options for doing so. Among these:

You can check your changes into a version control system, retrieve those changes on the second computer that is also running a CollectionSpace system, and perform the steps below directly on that second computer.
Once you've performed the one-time steps below, to create and modify the files and folders for your new tenant, you can mount a filesystem from your second CollectionSpace host computer on your own computer, and deploy (push) changes directly to that computer's disk. You will also need to set the CSPACE_JEESERVER_HOME and CATALINA_HOME environment variables to point to the Tomcat server folder on the filesystem you mounted from that second computer.

Browser not supported