...
Multiexcerpt | ||
---|---|---|
|
Procedure for creating a new tenant
Tip |
---|
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:
Code Block | ||
---|---|---|
| ||
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
Code Block | ||
---|---|---|
| ||
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.
Code Block | ||
---|---|---|
| ||
# 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
Code Block |
---|
ant clone-tenant |
Warning |
---|
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 |
Now run this command:
Code Block |
---|
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
Code Block |
---|
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
Code Block |
---|
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.
Code Block |
---|
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:
Code Block |
---|
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
Wiki Markup |
---|
{multi-excerpt:name=Procedure Create and modify}{multi-excerpt} |
- Make a new folder to contain the CollectionSpace source code for all three CollectionSpace layers. You might name it something like
cspace
orcollectionspace
or evencspace-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 toui
) 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
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 thecore
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
- Open the file
src/main/webapp/tenants/mymuseum/bundle/core-messages.properties-overlay
in a text editor.- Using your editor's global search and replace tool, globally replace, using case-sensitive replacement, every instance of
core
with demo.
- Using your editor's global search and replace tool, globally replace, using case-sensitive replacement, every instance of
Deploy (push) your new tenant to the CollectionSpace server
Code Block |
---|
mvn clean install
|
...
Application layer
Create and modify the Application layer files and folders for your new tenant
...
Procedure for creating a new tenant
Tip |
---|
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:
Code Block | ||
---|---|---|
| ||
We are going to update the tenant.properties
file with a few details
Code Block | ||
---|---|---|
| ||
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.
Code Block | ||
---|---|---|
| ||
Save that file and run the clone tool from the command line
Code Block |
---|
Warning |
---|
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 |
Now run this command:
Code Block |
---|
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
Code Block |
---|
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
Code Block |
---|
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.
Code Block |
---|
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:
Code Block |
---|
The less-easy way
Make a folder/directory to hold the source code for all three CollectionSpace layers: Services, Application, and UI
Wiki Markup |
---|
{multi-excerpt:name=Procedure Create and modify}{multi-excerpt} |
- Make a new folder to contain the CollectionSpace source code for all three CollectionSpace layers. You might name it something like
cspace
orcollectionspace
or evencspace-source
, for example.
Anchor | ||||
---|---|---|---|---|
|
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 toui
) 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 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 thecore
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 - Open the file
src/main/webapp/tenants/mymuseum/bundle/core-messages.properties-overlay
in a text editor.- Using your editor's global search and replace tool, globally replace, using case-sensitive replacement, every instance of
core
with demo.
- Using your editor's global search and replace tool, globally replace, using case-sensitive replacement, every instance of
Deploy (push) your new tenant to the CollectionSpace server
Code Block |
---|
Info |
---|
This will package up your new tenant, along with other UI-related files, into a |
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 toapplication
) 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 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 - Open the file
tomcat-main/src/main/resources/{mymuseum}-tenant.xml
in a text editor.- Using your editor's global search and replace tool, globally replace, using case-sensitive replacement, every instance of
core
withdemo.
- Using your editor's global search and replace tool, globally replace, using case-sensitive replacement, every instance of
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 thecore
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 - Open the file
tomcat-main/src/main/resources/tenants/demo/settings.xml
in a text editor.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 examplewalkerart.org
orucjeps.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 weremymuseum.org
:Code Block - Using your editor's global search and replace tool, globally replace, using case-sensitive replacement:
- Every instance of
core
withdemo
Every instance of
Core
withDemo
After making this change, here's an excerpt from what part of that file should now look like:Code Block
- Every instance of
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 thedemo
tenant has been changed from its default value of1
to a new value of 5:Code Block 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
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 aAnchor separate-database-for-tenant separate-database-for-tenant <name>
<repository>
See Storing your museum's data in its own database for more information on this option.
In the example below, a<name>
mymuseum_domain
. This will result in the creation of a database namedmymuseum_domain
,mymuseum
tenant:Code Block - 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:
Code Block
Info |
---|
In part, this will deploy (push) the |
Services layer
Wiki Markup |
---|
{multi-excerpt:name=Procedure Services layer}{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 toservices
) 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 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 thecore
folder. (That is, both folders should be contained within the same parent folder. Recall that there is a second identically-namedservices
folder just underneath the top-levelservices
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
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
- Open the file
tomcat-main/src/main/resources/{mymuseum}-tenant.xml
in a text editor.- Using your editor's global search and replace tool, globally replace, using case-sensitive replacement, every instance of
core
withdemo.
- Using your editor's global search and replace tool, globally replace, using case-sensitive replacement, every instance of
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 thecore
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
- Open the file
tomcat-main/src/main/resources/tenants/demo/settings.xml
in a text editor.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 examplewalkerart.org
orucjeps.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 weremymuseum.org
:Code Block <settings> <admin> <username>admin@demo.example.org</username> ...
- Using your editor's global search and replace tool, globally replace, using case-sensitive replacement:
- Every instance of
core
withdemo
Every instance of
Core
withDemo
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> ...
- Every instance of
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 thedemo
tenant has been changed from its default value of1
to a new value of 5:Code Block <settings> <admin> ... <tenant>5</tenant>
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>
- Save your modified file,
tomcat-main/src/main/resources/tenants/demo/settings.xml
<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> |
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:
Code Block mvn clean install -DskipTests
Info |
---|
In part, this will deploy (push) the |
Services layer
Wiki Markup |
---|
{multi-excerpt:name=Procedure Services layer}{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 toservices
) 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
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 thecore
folder. (That is, both folders should be contained within the same parent folder. Recall that there is a second identically-namedservices
folder just underneath the top-levelservices
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.
Inside the newly copied
demo
folder, rename thecore-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
- 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 ofdemo
in this file path.) You'll need to make two changes to this file.Enable the
<tenant>
element by removing the XML comment markers,<!–
and–>
, that directly surround it.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>
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
...
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 thecore-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 - 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 ofdemo
in this file path.) You'll need to make two changes to this file.Enable the
<tenant>
element by removing the XML comment markers,<!–
and–>
, that directly surround it.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
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
...
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
Wiki Markup |
---|
{multi-excerpt:name=Deploy Services layer}{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:
Code Block
...
ant import
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
...
MultiExcerptName | Test |
---|
...
- 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 wasdemo.example.org
, you would enter:admin@demo.example.org
In the Password field of the Sign In screen, enterAdministrator
, which is the default password for that user.
Click the *Sign In* button.
...
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:
Code Block |
---|
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
Multiexcerpt | ||
---|---|---|
| ||
Initialize Authorities and Term Lists
...