Page Comparison

...

Install CollectionSpace

Start the CollectionSpace Server

Verify that your CollectionSpace installation is working

Verify that you can log in to the core tenant - a generic demonstration tenant that comes as a standard part of your CollectionSpace system - by visiting http://{myhostname}:8180/collectionspace/ui/core/html in a web browser, where myhostname 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 Procedural Records heading, click the button next to Group
3. Click Create
4. Enter a value, such as My First Group, into the Title field
5. Click Save A message similar to Group successfully saved should appear.

If the save succeeds, verify that you can search for this record:

1. Enter First into the Search box at upper right
2. Click Search

A list of matching Group records should now be displayed.

Shut down the CollectionSpace Server

Pick a short name for your museum

For starters, pick 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

for examples below we will use demo

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

for examples below we will use demo.example.org.

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:

cd $HOME

# Change into the directory that contains your CollectionSpace source code.
# For example, if that directory is named "collectionspace-source", enter:
cd collectionspace-source

# *If* you've used the automated installer, that directory will likely be
# named "cspace_source", so instead enter:
cd cspace_source

ls 
> application   services   ui 

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

cd application
vim tenant.properties

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.

# 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
#
# Where there are conflicts, values provided via the command line
# are used in preference to those provided in this properties file.
# The "short name" of 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
# (pick an an integer between 100 - 199)
# example: tenant.id=101
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

Now run this command:

mvn clean install -DskipTests # compile the new configuration

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

echo Copy the tenant.properties file we modified from the applications directory to the services and ui directories.
cp tenant.properties ../services
cp tenant.properties ../ui

cd ../ui
ant clone-tenant
mvn clean install -DskipTests
 
cd ../services
ant clone-tenant
mvn clean install -DskipTests

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

echo From the top-level services directory, run the 'ant undeploy deploy' command
ant undeploy deploy

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.

ant import

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:

http://localhost:8180/collectionspace/ui/<your_tenant_short_name>/html/index.html

The less-easy way

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

{multi-excerpt:name=Procedure Create and modify}{multi-excerpt}

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:

   Code Block
   cd ui

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:

   Code Block
   cp -R src/main/webapp/tenants/core src/main/webapp/tenants/demo

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

mvn clean install

...

Application layer

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

...

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

{multi-excerpt:name=Procedure Create and modify}{multi-excerpt}

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:

   Code Block

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:

   Code Block

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:

   Code Block

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:

   Code Block

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:

   Code Block

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:

      Code Block

   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:

        Code Block

   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:

      Code Block

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

      Code Block

9. Anchor
   separate-database-for-tenant separate-database-for-tenant

   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:

   Code Block

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:

   Code Block

Services layer

{multi-excerpt:name=Procedure Services layer}{multi-excerpt}

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:

   Code Block

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:

   Code Block
   cd application

6. 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:

   Code Block
   cp tomcat-main/src/main/resources/core-tenant.xml tomcat-main/src/main/resources/demo-tenant.xml

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

8. 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:

   Code Block
   cp -R tomcat-main/src/main/resources/tenants/core tomcat-main/src/main/resources/tenants/demo

9. 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:

      Code Block
      <settings> <admin> <username>admin@demo.example.org</username> ...

   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:

        Code Block
        <settings> <admin> ... <tenantname>demo</tenantname> ...

   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:

      Code Block
      <settings> <admin> ... <tenant>5</tenant>

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

      Code Block
      <settings> <persistence> <service> ... <tenant> <id>5</id>

Anchorseparate-database-for-tenantseparate-database-for-tenantRecommended: 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:

Code Block
<repository> ...  <name>demo_domain</name>

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:

   Code Block
   mvn clean install -DskipTests

Services layer

{multi-excerpt:name=Procedure Services layer}{multi-excerpt}

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:

   Code Block
   cd services

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:

   Code Block
   cp -R services/common/src/main/cspace/config/services/tenants/core services/common/src/main/cspace/config/services/tenants/demo

   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:

   Code Block
   mv services/common/src/main/cspace/config/services/tenants/demo/core-tenant-bindings.delta.xml services/common/src/main/cspace/config/services/tenants/demo/demo-tenant-bindings.delta.xml

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: 

      Code Block
      <tenant:tenantBinding id="1"> </tenant:tenantBinding>

      to

      Code Block
      <tenant:tenantBinding id="5"> </tenant:tenantBinding>

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:

   Code Block
   mvn clean install -DskipTests

   Note
   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. On many systems, you can simply select the folder, copy the folder, paste it into the same location, and rename it.

2. 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:

   Code Block

3. 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: 

      Code Block

      to

      Code Block

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

   Code Block
   ant undeploy deploy

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

   Info
   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

...

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

{multi-excerpt:name=Deploy Services layer}{multi-excerpt}

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:

   Code Block

...

ant import

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

...

...

1. In the Email field of the Sign In screen, enter admin@demo.example.org, where {your_Internet_domain} is the Internet domain of your museum.
   For example, if your museum's Internet domain was demo.example.org, you would 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.

...

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

   Info
   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

...