•   31/12/1969 7:00 PM
•  
  • Misc - Private

JBoss Application Server is a full featured, royalty free, Open Source, Sun certified J2EE application server. For more information on the providers of this software, please visit http://www.jboss.org. The JBoss server package that is available to you in your eApps VPS service includes the embedded Tomcat application server, which is used to serve JSP pages and Java servlets. For more information on this open source, royalty free software please see The Apache Software Foundation's web site at http://jakarta.apache.org/tomcat/index.html.

The eApps Hosting service is designed to make it easy to use JBoss for serving J2EE applications in your Virtual Private Server (VPS). This User Guide is not intended as a reference source for JBoss. See the Links to other information at the end of this document if you need detailed information about JBoss. The purpose is to explain how to deploy your JBoss application in your VPS on the eApps Hosting service. If you follow the guidelines explained in this User Guide you will remain safely inside the eApps Support envelope. If you choose to use a custom configuration that is outside of the guidelines contained in this document, you may be subject to service fees if you need assistance from the eApps Support department. If you have any questions about this User Guide please contact support@eapps.com for assistance.

Requirements
How to Use JBoss
Tuning JBoss
Common Issues and Solutions
Links to other information

Requirements

At a minimum, you will need to have the Java and the JBoss application server installed in your VPS. These are available as applications in your VPS. They can be selected during the initial order process, or can be installed from the Add Application area on the System tab of your control panel after your VPS has been created. Unless your application requires otherwise, we recommend that you select the latest version of Java. You should not install the Tomcat application because it is bundled together with JBoss and will be available as a component of the JBoss application.

Depending on which approach you choose to deploy your JBoss application, as explained in the How to Use JBoss section below, you may also need to install Mod_jk, an Apache module that allows Apache to serve as a front end to the Tomcat component of JBoss.

JBoss is not available in the Standard and Standard Plus plans due to memory requirements. The Standard Max plan does have enough memory to run JBoss and serves as our entry level plan for JBoss users. However, it is important that you select a plan that has enough memory for your application during peak usage. If you do not need the advanced features of JBoss, and just need support for JSP and Servlets, we recommend that you uninstall JBoss and install Tomcat uses less resources.

How to Use JBoss

This section explains:

• Overview of three approaches for deployment
• How JBoss handles requests
• Understanding JBoss configuration files
• Server Configurations
• Starting and stopping JBoss
• Deployment Examples
• Using the JBoss jmx-console and web-console

Overview of three approaches for deployment

Your eApps Virtual Private Server includes the Apache web server as part of the base environment. Apache is designed to serve static content, perl scripts, php scrips, and other types of content that requires a web server. JBoss is designed primarily to serve JBoss specific applications, J2EE applications, JSP pages and servlets. One of the decisions you will need to make when deploying your JBoss application relates to how you want JBoss and Apache to interact. In most cases you will want to use Apache as a front end to JBoss. In some cases you may want to run JBoss without Apache. This section explains three approaches for your deployment.

eApps Hosting supports three approaches to deploy your JBoss application. Before you proceed you will need to determine which of the three approaches below is appropriate for you.

• Apache as a front end to JBoss using mod_jk - this approach allows you to control what content is served by JBoss and what content (if any) is served by the Apache web server. You will need to specify directives that tell Apache what content to pass on to JBoss. Mod_jk is mature, widely used, and also has advanced features for load balancing and other techniques. The majority of eApps customers use this approach.

• Apache as a front end to JBoss using mod_proxy_ajp - this approach is similar to mod_jk but is simpler to use and allows you to take better advantage of Apache's capabilities, such as mod_rewrite. It provides features for load balancing as well, but is not as sophisticated as mod_jk. Mod_proxy_ajp is a new approach and in fact does not work with Apache versions prior to 2.2. This approach can only be used by eApps customers running on the CentOs 5 or later version of operating system. To verify what OS you are on login to your control panel, click on the My Account tab, then the Subscription for your VPS. You will see the operating system version at the top.

• JBoss standalone (without Apache) - this approach allows you to run JBoss without Apache. JBoss has a built in web server so Apache is not strictly needed even if web pages need to be served. Since all requests are directed to JBoss, it theoretically is more efficient than approaches that use Apache as a front end, although the difference is not meaningful for most deployments. One major shortcoming is that the eApps Hosting service uses the Apache web server to serve all web based applications such as AWStats, Web mail, PHP applications, etc. Running JBoss standalone results in these applications being unavailable to you, by default, in your eApps VPS. This approach is generally used when deploying a commercial or open source application for a specific purpose and that is all that the VPS is intended to be used for.

How JBoss handles requests

The first thing to understand is how JBoss maps a request to a given application. JBoss uses a Host and a Context to determine what application to serve. Upon installation, there is one Host already created, called 'localhost', which is also set as the default host. Since having a default host is mandatory, it is best to leave this Host as is and create others for your sites as needed.

When JBoss receives a request, it first looks to see if there is a Host configured that matches the domain name in the URL that was requested. It then looks inside each Host to see if there is an Alias that matches the domain name in the URL. If it does not find either one, it then uses the Host that is set to the default. Note that http://mydomain.com and http://www.mydomain.com are two different possible Host names. If you want to configure your app to listen on both, you will need to set one as the name for the Host, and the other as an Alias.

After JBoss identifies the correct Host, it then looks at the rest of the URL to get the path of the application and tries to match that with a Context inside the jboss-web.xml file of one of the applications that are deployed.

Understanding JBoss configuration files and directories

The location of a JBoss configuration file varies depending on what you are trying to configure. However JBoss it's self is installed in /opt/jbossX (where X represents the version of JBoss you are using - for this user guide we will assume JBoss 4). The following are the primary files you will need to edit and their locations. You will need a text editor to modify the files. Root privilege is also required. If there are no applications currently live in production it is best that you stop the JBoss service first, as explained in the next section.

Deploy Directory - Since we use the default configuration at eApps, the deploy directory for you applications is /opt/jboss4/server/default/deploy.

server.xml - This is the primary file used to configure the JBoss server. This file is located in /opt/jboss4/server/default/deploy/jboss-web.deployer for JBoss 4.2.x users.

jboss.conf - located in directory /etc/jboss4, this is the configuration file for the Java Service Wrapper. eApps uses the Java Service Wrapper to run JBoss as a Linux Daemon/Service. This configuration file is used to set your parameters for JBoss and Java as suppose to the run.sh.

users.properties - Locate in /opt/jboss4/server/default/conf/props/, this file is where the user name and the password for the web-console and jmx-console are set with the defaults below.

admin=yourdomain.com #admin being the user and yourdomain.com as the password.

roles.properties - located in /opt/jboss4/server/default/conf/props/, this file the user roles for the web-console and jmx-console are set with the defaults below.

admin=JBossAdmin # admin being the user and JBossAdmin as the role.

Server Configurations

Starting from JBoss 4.2.x, the instance of JBoss provided by eApps supports 3 server configurations. The configuration that is used depends on the -c option that is passed to the startup script. Each configuration is in /opt/Jboss4/server/[config-name]. The configuration you use will determine the default services JBoss will make available to your application.

• Minimal Configuration (/opt/jboss4/minimal): The configuration starts the core server without any enterprise services.
• Default Configuration (/opt/jboss4/default): This is the most common configuration use. It provides support for J2EE 1.4 and your most common Java EE 5.0 API's such as EJB3 and JSF.
• All Configuration (/opt/jboss4/all): The configuration provides clustering support and extensions extensions.

eApps uses the default configuration option for running JBoss and this documentation will focus on deploying your application with those services though the steps can be applied to the other options by simply just replacing /opt/jboss4/default with the path of the configuration you desire. Please see the JBoss documentation at Jboss.org for details on using the minimal and all configuration options. To change the the server configuration mode in your VPS open the file /etc/jboss4/jboss.conf in a text editor and...

change...

set.JBOSS_CONFIG=default

to...

set.JBOSS_CONFIG=minimal or set.JBOSS_CONFIG=all

After this change the JBoss service will have to be restarted. Please see the section on Starting and Stopping JBoss.

Starting and stopping JBoss

To start or stop the Jboss server, you can use the command line or the Control Panel.

Command line - From the command line JBoss can be started and stopped with the commands below.

service jboss4 start
service jboss4 stop

or

/etc/init.d/jboss4 start
/etc/init.d/jboss4 stop

control panel - use the JBoss icon on the System tab of your Control Panel or the Services icon on the System tab (control for all services in your VPS)

Deployment examples for each of the three supported approaches

Apache as a front end using mod_jk

Apache runs securely on port 80. JBoss runs securely on port 8080, which means that the default URL of your application will be something like http://mydomain.com:8080/ or http://mydomain.com:8080/mywebapp. With mod_jk, you will be able to run JBoss securely on it's normal port and have Apache forward requests to JBoss. This will eliminate the 8080 from the URL.

When using the mod_jk approach, please make sure that the mod_jk application is installed. Verify this in the Applications area on your System tab in the control panel. When mod_jk is installed, default directives are created. These can be seen in the Custom Settings tab, in the Website settings area on the Site tab in your control panel. The mod_jk directives must be specified in the control panel! If you edit the httpd.conf file directly your settings will be overridden when certain system events cause the control panel to be resynchronized with Apache. Here are the default mod_jk directives:

JkMount /*.jsp ajp13
JkMount /*.do ajp13
JkMount /manager* ajp13 ##### Tomcat manager application
JkMount /admin* ajp13 ##### Tomcat administration application
JkMount /web-console* ajp13 ##### JBoss web console application

The examples below explain how to add the appropriate mod_jk directives. You may skip directly to the examples. If you are interested, here is a brief overview of a jkmount directive. See the Links to other information for additional reference sources on using mod_jk.

JKMount Overview - For each of your web sites, you can forward content to JBoss from the Apache Web Server using the JkMount directive. Use your Control Panel to define the directives for a specific web site. These directives will automatically update the httpd.conf file safely, since it is not advisable to edit httpd.conf directly.

The standard format for a simple JK mount is:

Apache as a front end using mod_proxy_ajp

Mod_proxy_ajp is an extension of the mod_proxy module that is available in Apache 2.2. The required modules are installed automatically if you have JBoss installed and have an eApps VPS running the CentOS 5 operating system or higher version. The mod_proxy_ajp directives must be specified in the control panel! If you edit the httpd.conf file directly your settings will be overridden when certain system events cause the control panel to be resynchronized with Apache.

Examples using mod_proxy_ajp:

ProxyPass /mywebapp ajp://localhost:8009/mywebapp

Using JBoss Standalone (Redirecting Requests to JBoss with Xinetd)

There are some situations where having Apache as front end to JBoss is not an option due to requirements by your application. To serve your content with out including 8080 and the end of your URL it means JBoss will have to listen on port 80.

For a service to be able to bind to a port number below 1024 it must have root privilages. In the case of JBoss this is a security risk because unlike Apache it's not able to start as root and drop back down to an unprivileged user. The safest way to serve JBoss content over port 80 without Apache is through Xinetd. Xined enables us to keep JBoss running on port 8080 and have requests to port 80 redirected to port 8080. So for this approach we will disable Apache and configure xinetd to forward port 80 requests to JBoss.

NOTE: Apache is part of the base environment of the eApps hosting service. The examples explain how to disable Apache. Do not uninstall Apache! Certain system events will synchronize your VPS to the standard base configuration and may automatically re-install Apache without your knowledge.

Examples using Standalone (Xinetd) approach:

How to use the JBoss jmx-console and web-console

Using The JBoss jmx-console

After JBoss has been installed you can access the Jmx-console at http://mydomain.com://8080/jmx-console. The default username and password is admin/mydomain.con (the VPS hostname at the time JBoss was installed. The JMX console provides a raw view into the microkernel of the JBoss application server. It lists all registered services (MBeans) that are active in the application server and that can be accessed either through the JMX console itself or programmatically from Java code.

Using The JBoss web-console

After JBoss has been installed you can access the web-console at http://mydomain.com:8080/web-console. The default username and password is admin/mydomain.com (the VPS hostname at the time jboss was installed) The web console provides a tree like view of management statistics on several things such as servlet, ejb, user defined domains and Mbeans.

Securing The jmx-console and web-console

The default username and password for the jmx-console and the web-console are the same and are managed by the user.properties files. The file is located in /opt/jboss4/server/default/conf/props.

If you wanted to change the user, as an example, to eapps and the password to hosting open the users.properties file in your text editor change . . .

admin=mydomain.com (or you VPS hostname)

to . . .

eapps=hosting

Next you will need to change the default role (admin) to your new user. To do this open the roles.properties file located in /opt/jboss4/server/default/conf/props and change . . .

admin=JBossAdmin

to . . .

eapps=JBossAdmin

Multiple users can be added in the format above. After making changes to this file you must restart JBoss for the changes to take effect.

Tuning JBoss

Optimize Java Memory (heap)

Java Heap size is the amount of memory allocated to the Java Virtual Machine (JVM). The heap is where Java objects live, and there must be enough memory allocated to your JVM to support the needs of your JBoss application. By default JBoss is configured to use a maximum of 128MB of RAM allocated to the Java heap. It is more than likely that you will want to change this setting. The first step will be to find out how much your JBoss Server will need. To do this stop JBoss, if its running, run free -m, multiply the used value by 2 and subtract that amount from the total allocated ram for your VPS. The result should give you a rough idea of the maximum you should set your JBoss RAM. If you run out of heap space, you might see the java.lang.OutOfMemoryError in your /var/log/jboss4/default/server.log. Normally it is not a good idea to allocate more than half of your total physical RAM as Java heap size. The chart below lists the allocated memory (RAM) limit by your plan with a guideline for the maximum heap setting.

If you are still getting "out of memory" errors after adjusting the heap settings (as explained below), you should run the Linux "free" command to determine if you are hitting memory limits. Note: These numbers are a general recommendation for most customers, and will vary greatly depending on how many applications you have installed, how much memory your Java application needs, as well as other factors and processes in your VPS. Contact eApps Technical Support if you have any questions.

Adjusting the Heap settings - To set the Java Heap for JBoss you must modify the wrapper.java.initmemory and the wrapper.java.maxmemory settings in your /etc/jboss4/jboss.conf file. It is best to set the init parameter lower than the maximum parameter to ensure that Java does not initialize more memory than is actually needed. This will optimize memory for non-Java processes.

Default values

# Initial Java Heap Size (in MB)
wrapper.java.initmemory=64

# Maximum Java Heap Size (in MB)
wrapper.java.maxmemory=128

Example: set the minimum heap to 256 MB and maximum heap to 512 MB

# Initial Java Heap Size (in MB)
wrapper.java.initmemory=256

# Maximum Java Heap Size (in MB)
wrapper.java.maxmemory=512

Remove Unused Applications (Experienced User Only)

The more applications you have deployed the slower startup time is. Run time performance can also be effected by this. You can increase these by removing applications that are not in use. The applications you deployed that are not in use our service porvided by jboss that you are not using.

Turn off Debug Information in JSP Classes

The JSP compiler compiles JSP classes in debug mode. In production systems you should turn this off.

cd /opt/jboss4/server/default/deploy/jboss-web.deployer/conf

edit web.xml and inclide the parameters in blod inside the jsp servlet.

<servlet>
<servlet-name>jsp</servlet-name>
<servlet-class>org.apache.jasper.servlet.JspServlet</servlet-class>

<init-param>
<param-name>fork</param-name>
<param-value>false</param-value>
</init-param>
<init-param>
<param-name>xpoweredBy</param-name>
<param-value>false</param-value>
</init-param>

<init-param>
<param-name>classdebuginfo</param-name>
<param-value>false</param-value>
</init-param>

</servlet>

Turn Development Mode off

With deployment mode set to true jboss will check for a new version of a jsp everytime it is accessed from the cline side and attempts to reload. The is option should be set to false especially in production systems.

cd /opt/jboss4/server/default/deploy/jboss-web.deployer/conf

edit web.xml and inclide the parameters in blod inside the jsp servlet.

<servlet>
<servlet-name>jsp</servlet-name>
<servlet-class>org.apache.jasper.servlet.JspServlet</servlet-class>

<init-param>
<param-name>fork</param-name>
<param-value>false</param-value>
</init-param>
<init-param>
<param-name>xpoweredBy</param-name>
<param-value>false</param-value>
</init-param>

<init-param>
<param-name>development</param-name>
<param-value>false</param-value>
</init-param>

</servlet>

There are several other things that can be done to tune Tomcat which are out of the scope of this documentation. Please see the Links to other information section below for external resources.

Use Database Connection Pool (DBCP) When Necessary

Connection pool can reduce connection creation time and resource usage especially on sites with high load. The steps below can help you implement Database Connection Pool for your application deployed on Tomcat.

For MySQL 

<datasources>

  <!-- Data Source -->
  <local-tx-datasource>

    <jndi-name>appnameDS</jndi-name>
   <connection-url>    
      jdbc:mysql://localhost:3306/appdb?autoReconnect=true    </connection-url>
    <driver-class>      
       com.mysql.jdbc.Driver    </driver-class>

    <user-name>dbuser</user-name>
    <password>dbpassword</password>

    <!-- Driver Specific Options --> (optional)
    <connection-property name="sendStringParametersAsUnicode">
      false
    </connection-property>

    <!--pooling parameters-->
    <min-pool-size>5</min-pool-size>
    <max-pool-size>100</max-pool-size>

    <blocking-timeout-millis>5000</blocking-timeout-millis>
    <idle-timeout-minutes>15</idle-timeout-minutes>

  </local-tx-datasource>

</datasources>

For PostgreSQL

<datasources>

  <!-- Data Source -->
  <local-tx-datasource>

    <jndi-name>appnameDS</jndi-name>
    <connection-url>      
     	jdbc:postgresql://127.0.0.1:5432/appdb    </connection-url>
    <driver-class>        
   	org.postgresql.Driver    </driver-class>
	<user-name>dbuser</user-name>
    <password>dbpassword</password>

    <!-- Driver Specific Options --> (optional)
    <connection-property name="sendStringParametersAsUnicode">
      false
    </connection-property>

    <!--pooling parameters-->
    <min-pool-size>5</min-pool-size>
    <max-pool-size>100</max-pool-size>

    <blocking-timeout-millis>5000</blocking-timeout-millis>
    <idle-timeout-minutes>15</idle-timeout-minutes>

  </local-tx-datasource>

</datasources>

2. jboss-web.xml Configuration

You now need to configure you application
WEB-INF/jboss-web.xml file to use the database resource. In your jboss-web.xml
file add a resource reference like the one below. 

for both MySQL and PostgreSQL

<resource-ref>
      <res-ref-name>jdbc/appnameDS</res-ref-name>
      <jndi-name>java:appnameDS</jndi-name>
</resource-ref>

Common Issues and Solutions

Question: Why am I getting a "jdbc error"?
Answer: This is an indication that your application is having problems connecting to the database. Make sure your database server is installed and running. Make sure you have installed the JDBC driver, as explained in the user guide for the database server you are using. Make sure your jdbc conncetion string url is correct. Try to connect to the database with the username and password you are using in your application.

Question: Why am I getting a "class not found error"?
Answer: This is an indication that you are trying to use a lib that is not in your class path. Check that the jar file is in /opt/jboss4/server/default/lib or in your application/WEB-INF/lib directory.

Question: JBoss is not starting after I added a host. What can it be?
Answer: If JBoss fails to start after you added a Host there is most likely a configuration error in your server.xml file. Check and make sure all tags are properly closed and that there are no syntax errors.

Question: JBoss is not starting and never has, what am I doing wrong?
Answer: If JBoss fails to start right from the start, you probably do not have the Java language application installed. You will see an error "cannot initialize JVM" in the catalina.out error file. Go to the All Applications area on the System tab of your control panel and make sure you have the J2SE (java 5) or Java 6 application installed in your VPS.

Links to other information

JBoss Home Page: http://jboss.org/

JBoss wiki: http://www.jboss.org/wiki/Wiki.jsp

Apache 2.2 Documentation: http://httpd.apache.org/docs/2.2/

Mod_jk Home Page: http://tomcat.apache.org/connectors-doc/

eApps mod_proxy User Guide: http://support.eapps.com/hsp/mod_proxy_balancer

eApps Apache User Guide: http://support.eapps.com/apache