Installing Crowd WAR on JBoss

The standard Crowd installation guide tells you how to install the Standalone distribution of Crowd, which includes Apache Tomcat. You may wish to deploy Crowd on your own existing application server instead. For this purpose, we provide WAR (Webapp ARchive) distributions of the Crowd and CrowdID server applications.

This page shows one example - use it as a basis for other installations This page tells you how to deploy Crowd onto a JBoss Application Server. For other application servers, refer to the generic WAR setup guide. On this page, we have used PostgreSQL as an example of a database connected via a JNDI datasource. Crowd supports all the databases listed under supported platforms. Refer to Connecting Crowd to a Database for instructions on connecting Crowd to your database.

Step 1. Check the System Requirements

Please check that your database and server are supported and make sure that all dependencies are installed as described below, otherwise Crowd will not run properly.

Supported Platforms

Key: = Supported. = Not Supported

Java Version
JDK (1)	1.6, 1.5 1.4
Operating Systems
Microsoft Windows (2)
Linux / Solaris (2)
Apple Mac OS X (2)
Application Servers
Apache Tomcat	6.0.x (Crowd ships with Apache Tomcat 6.0.20) 5.5.x (Tested on 5.5.26)
Databases
MySQL (3)	5.0.37 and later
Oracle	10g (Tested on 10.2.0.1.)
PostgreSQL	8.x, 7.x
Microsoft SQL Server	2008, 2005
HSQLDB (4)	(For evaluation only.)
Web Browsers
Microsoft Internet Explorer (Windows)	8, 7 6
Mozilla Firefox (all platforms)	3.x 2.x
Safari	4.x
Opera

Notes:
1. JDK:

• It is not enough to have the JRE only. Please ensure that you have the full JDK. You can download the Java SE Development Kit (JDK) from the Sun website.
• Once the JDK is installed, you will need to set the JAVA_HOME environment variable, pointing to the root directory of the JDK. Some JDK installers set this automatically (check by typing 'echo %JAVA_HOME%' in a DOS prompt, or 'echo $JAVA_HOME' in a shell). If it is not set, please see Setting JAVA_HOME.

2. Operating systems: Crowd is a pure Java application and should run on any platform provided the Java runtime platform requirements are satisfied.

3. MySQL: Please ensure that you set transaction isolation to 'read-committed' instead of the default 'repeatable-read', as described in the database configuration guide.

4. HSQLDB: Crowd ships with a built-in HSQL database, which is fine for evaluation purposes but is somewhat susceptible to data loss during system crashes. For production environments we recommend that you configure Crowd to use an external database.

Dependencies

Ensure that the following JAR files are deployed in the shared lib folder on the application server:

• JTA (Java Transaction API)

  The JTA specifies standard Java interfaces between a transaction manager and the parties involved in a distributed transaction system: the resource manager, the application server and the transactional applications. Refer to the Sun documentation for more information.

• JavaMail classes
• Java Beans Activation Framework (for those using Sun JDK 1.5.x only, this is included in JDK 1.6)
  
  All of these JAR files are available in the Crowd Standalone Distribution zip file, available on the Crowd download centre. The files are: activation-1.1.jar, jta-1.0.1B.jar and mail-1.4.jar. You will find them in {CROWD_INSTALL}\apache-tomcat\lib (for Crowd 2.0.2 or later) or in {CROWD_INSTALL}\apache-tomcat\common\lib (for Crowd 2.0.1 or earlier).

Step 2. Install Crowd WAR

Follow the steps below to install Crowd on JBoss 4.2.2 GA using a PostgreSQL database:

1. Download the WAR distribution from the Crowd download centre.
   You will find the WAR archives for the Crowd and the CrowdID applications. You will need to deploy Crowd and CrowdID WARs separately. For the rest of these instructions, we assume you are deploying Crowd WAR.
   
   
2. Please check your unzip program before extracting the downloaded archive, as some unzip programs can cause errors – see the note on the Crowd installation front page.
   
   
3. Unzip the download archive a directory named crowd.war inside JBOSS_INSTALL/server/default/deploy. In the rest of these instruction we will call this directory server/default/deploy/crowd.war.
   
   
4. Specify your Crowd Home directory by editing the configuration file at server/default/deploy/crowd.war/WEB-INF/classes/crowd-init.properties.
   

   The Crowd Home directory is where Crowd will store its configuration information. If you are using the embedded HSQL database, supplied for evaluation purposes, Crowd will also store its database in this directory. To specify the directory:

   • Open the crowd-init.properties file.
   • Choose the appropriate line in the file, depending upon your operating system (see below).
   • Remove the # at the beginning of the line.
   • Enter the name of the directory you want Crowd to use as its Home directory. For example,
     • On Windows:

       crowd.home=c:/data/crowd-home
       

       Note: On Windows, make sure you use forward slashes as shown above, not backward slashes.

     • On Mac and UNIX-based systems:

       crowd.home=/var/crowd-home
       

   • Save the crowd-init.properties file.
   
   
5. Add a file server/default/deploy/crowd.war/WEB-INF/jboss-web.xml with the following content:

   <jboss-web>
     <resource-ref>
       <res-ref-name>jdbc/CrowdDS</res-ref-name>
       <res-type>javax.sql.DataSource</res-type>
       <jndi-name>java:CrowdDS</jndi-name>
     </resource-ref>
   </jboss-web>
   

   
   
   

6. Create a database crowd_db in your database server. In our example, we assume you are using PostgreSQL.
   
   
7. Add a datasource definition file server/default/deploy/postgres-ds.xml that resembles the following example. Our example is for a PostgreSQL database:

   <datasources>
     <local-tx-datasource>
       <jndi-name>CrowdDS</jndi-name>
       <connection-url>jdbc:postgresql://localhost:5432/crowd_db</connection-url>
       <driver-class>org.postgresql.Driver</driver-class>
       <user-name>postgres</user-name>
       <password>postgres</password>
     </local-tx-datasource> 
   </datasources>
   

   
   
   

8. Modify your {CROWD_HOME}/crowd.properties file to point to the port of the JBoss server. This file is located at the root of your Crowd Home directory (specified above). Port 8080 is the default port number, and is shown in the example below:

   crowd.server.url=http://localhost:8080/crowd/services/
   application.login.url=http://localhost:8080/crowd/console/
   

   
   
   

9. Start JBoss with run.sh (Unix-based systems) or run.bat (Windows).
   
   
10. Point a web browser at http://localhost:8080/ where you will see the Crowd Setup Wizard.

RELATED TOPICS

• Supported Platforms
• Installing Crowd and CrowdID
• Running the Setup Wizard
• Configuring Crowd