XMCCat Server Binary Installation

Building XMC Cat Using Maven2 & Generating Binary

This section can be skipped if you choose to download binary directly from Sourceforge XMC Cat Server Binaries i.e. xmccat-war-1.0-bundle.tar. However, if you want to make changes to source code and want the binary to include these changes then follow the steps given in this section. After downloading the source tarball from the Sourceforge XMC Cat Source, unzip it in the directory of your choice. When extracted, the tarball will consist of a single directory named xmccat-server which we will refer to in this documentation as <source>. Once it is unzipped, XMC Cat can be compiled using Maven2 (please see the prerequisites page). With both Java and Maven2 in your classpath, switch to the <source> directory and type the following command to use Maven2 to build XMC Cat:

 mvn -e

The first time that you compile XMC Cat, you will need to be online so Maven2 can download the dependencies for the build. By default, Maven2 will download the necessary jars to the repository hierarchy of the .m2 directory contained within your home directory (Maven2 will automatically create the .m2 directory if it does not exist). Depending on the speed of your network connection, the first build will take much longer than subsequent builds on a slow internet connection.

Once the build is successful, switch to the xmccat-war directory inside the <source> directory and type the following command to use Maven2 to build the XMC Cat war tarball:

 mvn assembly:single

This will generate a file named xmccat-war-1.0-bundle.tar.gz in the <source>/xmccat-war/target directory. We will call this file war-tarball in the rest of these installation instructions.

Configuring Your Environment

When running the tomcat server for XMC Cat, the following environment variables should be set:

JAVA_HOME should be set to the root directory of your jdk installation.

MYSQL_HOME should be set to the root directory of your MySQL installation (the directory referred to as <mysql> in this guide).

CATALINA_HOME and CATALINA_BASE should both be set to the directory for the Tomcat installation you are using for XMC Cat (the directory referred to as <tomcat> in this guide).

Creating the XMC Cat Database in MySQL

The following assumes that you have MySQL installed and that you are using the default MySQL port of 3306 (you are if you did not change it). Log into MySQL as the root user and create a database named xmccat using the following command:

  CREATE DATABASE xmccat;

The rest of these instructions will assume you have used the default name "xmccat" for the database, but you can use whatever name you wish. We will point out where you would need to change the name in the configuration files if you use a different name.

Create a user account on MySQL that will be used to access the database from XMC Cat. To create the user account from the command line, log into MySQL as the root user and execute the following commands (replacing "xmccatuser" with the name of the user wish to create for XMC Cat to access the database and "catpw" should be replaced by the password you wish to use for your xmccat user).

The third GRANT statement is needed to allow stored procedures to be run.

  GRANT ALL ON xmccat.* TO 'xmccatuser'@'%' IDENTIFIED BY 'catpw';
  GRANT ALL ON xmccat.* TO 'xmccatuser'@'localhost' IDENTIFIED BY 'catpw';
  GRANT SELECT ON mysql.proc TO 'xmccatuser'@'localhost' IDENTIFIED BY 'catpw';

The user account and password you use here will need to added to configuration files for XMC Cat, so be sure you do not use a personal password that you use for other systems.

The XMC Cat database is empty at this point (no tables have been defined).

Installing Binary

Copy the war-tarball that we generated previously using the 'mvn assembly:single' command to the directory of your choice on the server. Follow the steps below to install XMC Cat:

1) Unzip the war-tarball in the directory you copied it to. When extracted, it consists of single directory named xmccat-war-1.0.

 tar xvzf xmccat-war-1.0-bundle.tar.gz

The xmccat-war-1.0 directory created contains all the files required to install XMC Cat, but you will only need to be concerned with two shell scripts: dbsettings.sh & xmccat-db-setup.sh. Don't delete any of the other files or directories - they are used by these scripts to run the installation. Please make sure that you have permission to execute both of these the scripts. To set execute permissions, change to the xmccat-war-1.0 and execute the following command:

 chmod u+x *.sh

2) If this is the first time you are installing XMC Cat and you don't have the database set-up for it then run the xmccat-db-set-up.sh script. It will prompt user to give database url, username & password. If the entered credentials are authentic then the tables will be created in the database & required stored procedures are loaded. Otherwise, it will give error message to user that one of the entered details is not valid, please verify and enter again.

3) Once the database is set-up then you are ready to install XMC Cat. For this, run the dbsettings.sh script. Like the previous script, it will also prompt you for the database url, username, and password along with the host and port on which the XMC Cat's tomcat will be running. To automated the installation, it also asks for tomcat directory path so it can copy the updated war file to the webapps directory of your tomcat. The tasks performed by this script can be summarized as follows:

  a) If DB credentials are correct it will unpack the xmccat-war-1.0.war file and make changes to the following files:
     1) META-INF/context.xml
     2) WEB-INF/web.xml
     3) WEB-INF/services/CatalogService/META-INF/services.xml
  b) Repack the war file as xmccat-war-1.0.war		
  c) Copies mysql-connector-java-3.1.11.jar to tomcat's lib folder
  d) Copies xmccat-war-1.0.war to tomcat's webapp folder		
  e) Changes the host & port properties in services.xml

4) Start the tomcat server

5) Open browser & enter url: http://host:port/xmccat-war-1.0