This documentation relates to an earlier CollectionSpace version.

This documentation is for version 2.0. The current version is 4.0.
View this page in the current documentation or visit the current documentation home.

Skip to end of metadata
Go to start of metadata

Due to reasons described at "Nuxeo API Issues", the CollectionSpace Service layer is split into two JBoss "domains": the "CollectionSpace" services domain and the Nuxeo services domain. This wiki page describes how to build and deploy those two service domains.

Assumptions for Building and Deploying the CollectionSpace Service layer

  1. JDK: Sun's Java Development Kit (JDK). Install JDK 6 if you haven't done so already. Set the JAVA_HOME environment variable to the directory on your local drive where JDK 6 is installed.
  2. MySQL: MySQL Community Server 5.1. Install and configure MySQL by following the instructions in Install and configure MySQL.

Step 1: Download or build domains

There are two approaches to crate the two JBoss domains of CollectionSpace.

  1. Download pre-built, pre-configured and tested domains from FTP server and explode the zips
  2. Roll your sleeves, build and configure the two domains by yourself

Considering the number of steps required to configure these domains and chances of errors, we recommend using pre-built domains.

Approach 1: Download pre-built and pre-configured domains (recommended)

Starting with the HelloMars release (v0.2), the quickest and easiest way to deploy the service layer is to download the zipped JBoss "domains" from the FTP server at source.collectionspace.org and unzip them in directory of your JBoss installation. This gives you pre-configured JBoss domains to start using right away. Instructions to download the domains is provided on Download the CollectionSpace domains.

Set JBOSS_HOME environment variable

The "JBOSS_HOME" environment variable should be set to the directory where you've installed JBoss and into which the two zipped "domain" files should be unzipped.

You could set the environment variable by opening a command prompt where you want to start the server.

Approach 2: Build and configure domains

Alternatively, you could build and configure the domains by yourself by following the instructions described below. In terms of the order, first configure the Nuxeo domain and then the CSpace domain.

  1. build and configure Nuxeo domain
  2. build and configure CSpace domain
Set JBOSS_HOME environment variable

Here as you have installed JBoss 4.2.3 GA, the directory where JBoss is installed is the directory pointed to by the JBOSS_HOME environment variable.

Step 2: Prepare database

Before starting the servers, it is required to prepare the database(s), create users (for testing) and assign privileges. Follow the instructions on Prepare database for CollectionSpace to accomplish this task.


Step 3: Service specific configuration

Some CollectionSpace services require additional steps to configure.

  1. Follow instructions on Authentication Service Configuration Guide to configure the default identity provider.
  2. Follow instructions on ID Service Configuration Guide to configure the ID Service.

Note Due to the modular nature of the services, these tasks are not yet consolidated.


Step 4: Starting the JBoss server domains.

Nuxeo domain

Note that if you have downloaded the Nuxeo domain from Download the CollectionSpace domains, you do not need to set JAVA_OPTS as described below.

  1. Before running JBoss with Nuxeo, you'll need to increase the memory allocation for permanent generation for HotSpot JVM. To do this, modify JAVA_OPTS in $JBOSS_HOME/bin/run.bat as follows:
    If you are using Unix, modify JAVA_OPTS in $JBOSS_HOME/bin/run.sh as follows, inserting this line before the section that is commented "# Read an optional running configuration file":
  2. Follow these additional steps to run JBoss with JDK 6 (recommended).
  3. Open a command prompt and execute the following command.

On successful startup, you may see output similar to the following on your console/log. Your server log could be found in $JBOSS_HOME/server/{domain}/log/server.log.

If you want to tee off the output and error to a different file, you could do the following.

Note In our experience the ERROR [PersistenceXmlLoader] and WARN [TagSchemaUpdater] do not seem to hinder functionality used by CollectionSpace.

Once the server is up and you see Nuxeo EP Started, point your browser to http://localhost:8080/nuxeo/ and login as Administrator/Administrator

This server should listen for HTTP requests on port 8080.

Create Nuxeo workspaces for CollectionSpace services
  1. Point your browser to the Nuxeo web application at http://localhost:8080/nuxeo
  2. Log in using Administrator/Administrator
  3. Click the "Workspaces" link in the default domain
  4. Create new Workspaces, one for each entity service.

    As of the Venus release, the following is the list of workspaces you will need to create:
    1. collectionobjects
    2. intakes
    3. relations
    4. acquisitions
    5. vocabularies
    6. vocabularyitems

Note that there is an outstanding issue CSPACE-375 for this problem. Once that is fixed, workspaces would be created by the service layer automatically.

CSpace domain

Open a command prompt and execute the following command.

This server should listen for HTTP requests on port 8180.

If both the servers come up without any port conflicts, consider that you are successful at this point.

Build the CollectionSpace services layer

Use the Maven build tool to build the CollectionSpace services layer from source code.

Open a command prompt and, from within your directory for the CollectionSpace Services Layer source code, execute the following command:

Icon

If you should encounter an "out of memory" error when performing this step, you can increase the memory allocation given to the Maven build tool.

Deploy the CollectionSpace services layer files to the servers

After you've built the services layer, you'll use the Ant build tool to deploy (copy) its deployment artifacts to the servers for the Nuxeo and CSpace domains. These artifacts include the services layer's jar files, configuration files, and other files.

Open a command prompt and, from within your directory for the CollectionSpace Services Layer source code, execute the following command:

The Ant deploy task copies deployment artifacts to both the Nuxeo and CSpace domains.

Because Nuxeo cannot 'hot deploy' document types, you may have to restart both the domains (Nuxeo first and then CSpace) before running any tests.

Verify the connection between the servers

CSpace domain

The CSpace domain server log should show something similar to the following.

  • Line #1 indicates successful connection between the Nuxeo client running inside CollectionSpace services and the Nuxeo server.
  • Lines #2-4 indicate that a repository session was established and the service layer was able to retrieve workspace ids from the remote Nuxeo repository.

Nuxeo domain

The Nuxeo domain server log should show something similar to the following.

Test and verify

Once you have built and deployed the CollectionSpace artifacts to the Nuxeo and CSpace domains, open a command prompt and, from within your directory for the CollectionSpace Services Layer source code, execute the following command to run tests:

This will run a bunch of tests for each service as well as for various other things. If you see the following output at the completion of the tests, build and deployment should be considered OK.

Note You may find the following warning on the console and log of the Nuxeo domain server after running the tests. It is OK to ignore it.

Gliffy Macro Error

You do not have permission to view this diagram.

Gliffy Macro Error

You do not have permission to view this diagram.

Rest of the document contains the following topics.


References

  1. Build Nuxeo 5.2
  2. Configure JBoss and Nuxeo to use MySQL
  3. Nuxeo 5.2, JBoss 4.2.3 and JDK 6
  4. JBoss Configure Ports

Recently Updated

3 Comments

  1. Does the "nuxeo-jboss-interceptors-4.2.3.GA.1.jar" file need to remain in the 'cspace' domain?

    1. I wasn't sure so I might have kept it as is if you are talking about the Nuxeo deployment from my system.

  2. With fix for Issue:CSPACE-242, it is no more required to start the server from the cspace directory.