JBoss Installation Guide

From jVantage

This document describes the steps required to install jVantage 1.rc1 on the JBoss Application Server.

Contents 1 Prerequisites 2 Setup the Database 2.1 Install the MySQL Driver 2.2 Create an Empty Database 2.3 Map a JBoss Datasource to the jVantage Database 2.3.1 Sample PostgreSQL Data Source 3 Install the jVantage EAR 4 Invoke the Setup Tool 5 If You Need Help

Prerequisites

Before jVantage can be installed, an instance of the JBoss application server must be installed and running on your server. When downloading jVantage, be sure that you download the proper version of jVantage for the JBoss instance you have. This information is provided on the jVantage download page.

A database is also required. This document assumes MySQL database 4.n or later.

Setup the Database

Install the MySQL Driver

A proper database driver must be installed in the JBoss application server’s lib directory to allow jVantage to communicate with the database. The MySQL driver can be downloaded from http://dev.mysql.com/downloads. Select and download a MySQL Connector/J driver type.

When the MySQL driver is downloaded, it typically comes packaged in a zip or tar file that contains source code and other resources along with the driver file itself. Unpack the zip or tar file you downloaded into a temporary directory, then copy the file named mysql-connector-java-3.n.n-bin.jar to the /<JBoss-Home>/server/default/lib directory; where the n.n can be any numbers reflecting the version of the driver file. For example:

$ cp mysql-connector-java-3.1.10-bin.jar /<JBoss-Home>/server/default/lib

The lib directory location can vary depending on your JBoss configuration if you have defined a custom server.

Create an Empty Database

This document assumes you have an existing, running instance of MySQL. If you don't, please visit http://www.mysql.com/ to download a copy. Installation instructions can also be found at this location.

Create an empty MySQL database for your jVantage installation using a command such as:

$ mysql

mysql>create database jvantage

quit

$

Although it is not strictly required, we highly recommend that you name your database jvantage until you become more familiar with the jVantage tool. On initial installation, jVantage defaults to this database name and it will simplify installation and reduce the possibility of encountering problems with the installation. After you become familiar with jVantage, you will see that the name can be anything you choose - you can even connect to multiple databases from a single jVantage instance.

Map a JBoss Datasource to the jVantage Database

Now that an empty database has been created, you must create a Datasource descriptor that tells JBoss how to find and communicate with it. You may use the following examples as starting points for creating your own descriptors. Edit this file to contain values that reflect your environment and MySQL database parameters as follows:

<?xml version="1.0" encoding="UTF-8"?>
<datasources>
 <local-tx-datasource>
   <jndi-name>jdbc/jVantageDS</jndi-name>
   <use-java-context>false</use-java-context>
   <connection-url>jdbc:mysql://databaseHostName/databaseInstanceName</connection-url>
   <driver-class>com.mysql.jdbc.Driver</driver-class>
   <user-name>your-mysql-user-name</user-name>
   <password>your-mysql-password</password>
 </local-tx-datasource>
</datasources>

The values should be repopulated as follows:

• databaseHostName: The name of the server machine where your MySQL database is running.
• databaseInstanceName: The name of the database. Set this to the name of the database you created above create database databaseName). If you followed the example, and created your database with the name jVantage (create database jvantage), the name should be set to jvantage. Note that the database name is case sensitive.
• your-mysql-user-name: The name of the user account as it is defined in your MySQL server.
• your-mysql-password: The password of your MySQL account.

For example:

<?xml version="1.0" encoding="UTF-8"?>
<datasources>
 <local-tx-datasource>
   <jndi-name>jdbc/jVantageDS</jndi-name>
   <use-java-context>false</use-java-context>
   <connection-url>jdbc:mysql://mysqlserver/jvantage</connection-url>
   <driver-class>com.mysql.jdbc.Driver</driver-class>
   <user-name>jdoe</user-name>
   <password>apple</password>
 </local-tx-datasource>
</datasources>

This datasource descriptor indicates that the server hosting the MySQL database is named mysqlserver. The database name is jvantage. The user name is jdoe and the password is apple.

After making these changes, copy the file to the JBoss server deployment directory (i.e., /<JBoss-Home>/server/default/deploy).

Sample PostgreSQL Data Source

<?xml version="1.0" encoding="UTF-8"?>
<datasources>
  <local-tx-datasource>
    <jndi-name>jdbc/jVantageDS</jndi-name>
    <use-java-context>false</use-java-context>
    <connection-url>jdbc:postgresql://localhost:5432/jvantage</connection-url>
    <driver-class>org.postgresql.Driver</driver-class>
    <user-name>jdoe</user-name>
    <password>apple</password>
  </local-tx-datasource>
</datasources>

Install the jVantage EAR

After installing the datasource descriptor, copy the following files to the JBoss deployment directory.

• jvantage-1.rc1.ear – jVantage enterprise archive.

Again, assuming that you are using the default server, the deployment directory is as follows: /<JBoss-Home>/server/default/deploy.

Invoke the Setup Tool

Once the appropriate files have been copied to the JBoss deployment directory, the Setup tool can be invoked. The tool can be accessed using the URL:

http://jbosshostname:<port>/jvantage/jvantage-setup

If your JBoss server has been configured to listen on port 80, the URL can be expressed as:

http://jbosshostname/jvantage/jvantage-setup

As shipped, JBoss is configured to use port 8080 – if you have not changed this configuration, the URL will be:

http://jbosshostname:8080/jvantage/jvantage-setup

Follow the instructions on the screen to complete the installation.

If You Need Help

If you need help installing jVantage, let us know. Please go to our online forums and post your question or comment and we will try to respond in a timely manner.

Thank you for downloading jVantage!