Applicable Plans - All Cloud Hosting Plans

JBoss 7 Installation and Tuning

Overview

Using the eApps Virtual Server in the Cloud Hosting service, Java SE 7, and JBoss 7, you can create web sites and web applications with dynamic content for your customers and users.

This User Guide is designed to help you install Java SE 7 and JBoss 7 on your Virtual Server, and to do basic tuning if necessary.

Information on how to actually deploy your applications using one of the three supported deployment methods (Apache with mod_jk, Apache with mod_proxy_ajp, and without Apache) are found in the User Guides specific to that method. The two approaches using Apache are covered in the same user guide.

• JBoss 7 Application Deployment with Apache Web Server

• JBoss 7 Application Deployment without Apache Web Server

Pay careful attention to the resources allocated to your Virtual Server when deploying JBoss 7 applications, especially the available RAM. JBoss can be very memory intensive, and a lack of resources is one of the main reasons for poor performance. For a small JBoss application, start with at least 1024 MB of RAM, and be prepared to scale upwards as necessary. For larger JBoss applications, start with at least 1536 MB of RAM, and again be ready to scale upwards if your traffic and resource needs demand it.

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 instead, as Tomcat uses less resources and is not as complex as JBoss to configure and use.

JBoss is a very complex and powerful application that is intended for advanced users who are deploying enterprise grade applications. Before deploying your applications with JBoss, make sure that you really need all the complexity that JBoss provides. To make the best use of JBoss you need to be an expert in Java application programming and deployment.

Installing JBoss 7
    Installing JBoss 7 using a Control Panel
    Installing JBoss 7 using the command line

Starting and Stopping JBoss 7
    Using the Control Panel
    Using the Command line

JBoss 7 Administration Console

JBoss 7 Deployment Approaches
    Overview of three approaches for deployment
    Using Apache and mod_jk
    Using Apache and mod_proxy_ajp
    Using JBoss without Apache

Tuning JBoss
    Set the Java Heap correctly
    How to find the correct Java Heap settings
    Adjusting the Java Heap settings

Installing JBoss 7

There are two choices for installing JBoss 7:

1. You can use the CentOS 6 64bit JBoss 7 (ISPmanager CP) template when you create your Virtual Server, which installs JBoss 7, Java SE 7, and mod_jk.

2. You can create your Virtual Server with one of the CentOS 6 ISPmanager CP templates, and install JBoss 7 and related applications individually. To run Java applications using JBoss 7, you will need to install JBoss 7, and Java SE 7. Install Java SE 7 - JBoss will not start if Java is not installed first.

For either installment choice, you will need to install either MySQL database server and Mysql JDBC Driver, or PostreSQL database server and PostgreSQL JDBC Driver. Which database you choose will depend on your existing codebase and preferences.

If you are going to use the mod_jk deployment method (used by the majority of eApps customers), you will need to install mod_jk. If you are going to use the mod_proxy_ajp deployment method, nothing additional needs to be installed because mod_proxy_ajp is an Apache module, and is available if Apache is installed.

If you are installing JBoss 7, make sure to install Java SE 7 FIRST. If you install JBoss 7 without a JVM installed, the JBoss 7 service will not start.

Installing JBoss 7 using a Control Panel

Installing JBoss 7 using the ISPmanager Control Panel

If you are using the ISPmanager Control Panel, you can install JBoss 7 and related applications from that Control Panel.

• For ISPmanager 4, go to Server Settings > Applications. Make sure to install Java SE 7 first, then install JBoss 7 and any other related applications. More information on installing applications can be found here - Installing Server Applications

• For ISPmanager 5, go to Settings > Features. Make sure to install Java SE 7 first, then install JBoss 7 and any other related applications. More information on installing applications can be found here - Installing Features (Server Applications)

Information on how to tell which version of ISPmanager you are using can be found here - ISPmanager versions

Installing JBoss 7 using the command line

You can install JBoss 7 and related applications from the command line of the Virtual Server. You will need to install Java SE 7 and several Java plugins first, and then install JBoss 7. All of this is done using yum.

To install Java SE 7 and the related applications, use the yum install -y java-1.7.0-sun java-1.7.0-sun-plugin java-1.7.0-sun-jdbc java-1.7.0-sun-src java-1.7.0-sun-devel java-1.7.0-sun-javafx command.

[root@eapps-example ~]# yum install -y java-1.7.0-sun java-1.7.0-sun-plugin java-1.7.0-sun-jdbc java-1.7.0-sun-src java-1.7.0-sun-devel java-1.7.0-sun-javafx

Note - if you still need to use Java SE 6 for legacy reasons, you can install it using the command above for Java SE 7, but substitute 6 for 7. Be aware that Java SE 6 is End Of Life, and may not be supported in the future.

To install JBoss 7, use the yum install -y jboss7 command.

[root@eapps-example ~]# yum install -y jboss7

If you are going to use the mod_jk approach for JBoss, you will need to install mod_jk using the yum install -y mod_jk.

[root@eapps-example ~]# yum install -y mod_jk

If you are going to install your database from the command line, please see the specific user guide for that database:

• Instructions for installing and configuring MySQL and phpMyAdmin from the command line are in the MySQL User Guide.

• Instruction for installing and configuring PostgreSQL and phpPgAdmin from the command line are in the PostgreSQL User Guide

Starting and Stopping JBoss 7

JBoss can be stopped, started or restarted from your Control Panel or from the command line of the server.

Using the Control Panel

Using ISPmanager

The way to start, stop, and restart JBoss from ISPmanager will depend on which version of ISPmanager you are using.

• For ISPmanager 4, go to Management Tools > Services, and highlight the jboss7 service. Then click on Stop, Start, or Restart in the upper right corner. More information about managing service in ISPmanager 4 is available here - Managing Services

• For ISPmanager 5, go to System > Services, and highlight the jboss7 service. Then click on Start, Stop, or Restart in the upper left corner. More information about managing services in ISPmanager 5 is available here - Managing Services

Using the Command line

This can be done by connecting to the command line of your VS - Connecting to your Virtual Server (SSH and MindTerm) - http://support.eapps.com/ispmgr/ssh. You will need to be the root user to run these commands.

Starting JBoss

Start JBoss with the service jboss7 start command.

[root@eapps-example ~]# service jboss7 start

Stopping JBoss

Stop JBoss with the service jboss7 stop command.

[root@eapps-example ~]# service jboss7 stop

Restarting JBoss

Restart JBoss with the service jboss7 restart command.

[root@eapps-example ~]# service jboss7 restart

JBoss Status

Check the status of JBoss with the service jboss7 status command.

[root@eapps-example ~]# service jboss7 status

JBoss 7 Administration Console

In JBoss 7, the jmx-console and the web-console have been replaced with the JBoss Administration Console. The Administration Console is the root context for the default JBoss 7 installation, and is available at http://eapps-example.com:8080 (substitute your own domain name or IP address for eapps-example.com).

This takes you to the Welcome to AS 7 page (for Application Server 7).

To access the Administration Console, click on the Administration Console link. You can also access the Administration Console directly by going to http://eapps-example.com:9990 (substitute your own domain name or IP address for eapps-example.com).

You will need to follow the instructions on this page to set a username and password for a user that can access the JBoss Administration Console. This needs to be done from the command line, as the root user. Namely, you will need to run the add-user.sh script in the /opt/jboss7/bin directory, adding the user to the ManagementRealm.

Connect to the VS using SSH, and change directories to /opt/jboss7/bin. Execute the add-user.sh script by typing in ./add-user.sh (a dot, a slash, and then add-user.sh, with no spaces)

When prompted, select a to create a Management User. The Username can only be alphanumeric characters, no special characters (!@#$ etc) are allowed. If your password is easily guessable, the script will warn you.

[root@eapps-example ~]# cd /opt/jboss7/bin/
[root@eapps-example bin]# ./add-user.sh
What type of user do you wish to add?
 a) Management User (mgmt-users.properties)
 b) Application User (application-users.properties)
(a): a

Enter the details of the new user to add.
Realm (ManagementRealm) :
Username : adminuser
Password :
Re-enter Password :
About to add user 'adminuser' for realm 'ManagementRealm'
Is this correct yes/no? yes
Added user 'adminuser' to file '/opt/jboss7/standalone/configuration/mgmt-users.properties'
Added user 'adminuser' to file '/opt/jboss7/domain/configuration/mgmt-users.properties'
[root@eapps-example bin]#

Once you have created the user for the Administration Console, click the Try Again link at the bottom of the page, or go to http://eapps-example.com:9990/ in your browser (make user to substitute your own domain name for eapps-example.com). This will take you to a page where you can enter the User Name and Password for the Administration Console.

More information on how to use the JBoss 7 Administration Console to deploy your application can be found in the User Guides for each deployment example.

JBoss 7 Deployment Approaches

Overview of three approaches for 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. The three supported approaches for deployment are:

1. Using Apache and mod_jk

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.

2. Using Apache and mod_proxy_ajp

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.

3. Using JBoss without Apache

JBoss without Apache - this approach should only be used if your application specifically requires this method. Generally, this approach is only used when your Virtual Server does nothing but run a JBoss application. In other words, it is not used for e-mail, or any other function other than the JBoss application. This approach is for advanced users who are already very familiar with configuring JBoss and Apache. The vast majority of users do not need this approach.

For instructions on how to use each of the three supported approaches, please see the User Guide for that specific approach. Note that mod_jk and mod_proxy_ajp are covered in the same User Guide.

• JBoss 7 Application Deployment with Apache

• JBoss 7 Application Deployment without Apache

Tuning JBoss

Set the Java Heap correctly

Java Heap Settings - an overview

The most common issue with JBoss, by far, is a lack of available resources. In many cases, this is due to the Java Heap size either not being configured at all, or not being configured correctly. In other cases, the plan is simply too small for the type of application being run on it. For example, while it is possible to run JBoss with only 768 MB of RAM, that plan does not have the resources for a true enterprise application or a site that receives a high volume of traffic.

One of the most important parts of tuning JBoss for better performance is to optimize the Java Heap settings. The 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 the JVM to support the needs of the deployed JBoss applications.

How to find the correct Java Heap settings

By default JBoss is configured to have an Initial Java Heap Size of 512 MB, and a Maximum Java Heap Size of 512 MB. Depending on your application and configuration, you may need to adjust this value in order to correctly optimize JBoss.

To find the correct heap size, you will have to stop JBoss, and use the Linux free -m command to see the available memory, and then multiply that value by two, and then subtract that result from the total RAM available for your plan. This number will be roughly what you need to set for the maximum heap size.

The following must be done from the command line of the VS. See the User Guide: Connecting to your Virtual Server (SSH and MindTerm) http://support.eapps.com/ispmgr/ssh for more information if needed.

[root@eapps-example ~]# service jboss7 status
JBoss Application Server is running (3027)
[root@eapps-example ~]# service jboss7 stop
Stopping JBoss Application Server...
Stopped JBoss Application Server.
[root@eapps-example ~]# free -m
             total       used       free     shared    buffers     cached
Mem:          2048        600       1448          0         30        706
-/+ buffers/cache:        154        869
Swap:         2047          0       2047
[root@eapps-example ~]#

In this example, with JBoss stopped, the operating system and all other applications and services running consume 600 MB of RAM.

Multiply this value by two giving a total of 1200, and subtract that from the total available RAM for a value of 848 MB for the maximum heap.

Remember, this is just a rough estimate. You may find that you need to adjust this number up or down as necessary, depending on how your application is configured and what other services your system is running.

Generally, the maximum heap size should be just under half the amount of memory available. You can of course adjust this value higher or lower, but you may have to experiment to determine the true optimum heap size

If your JVM runs out of heap space, the message java.lang.OutOfMemoryError may appear in the /var/log/jboss7/standalone file. This message lets you know that you need to either adjust your heap settings, consider upgrading your plan, or optimize your application to use less memory and resources.

You can also use the same free -m command as shown above, but with JBoss still running. This will show you if you are hitting memory limits in your plan. If your free memory drops below 100 MB, that is a sign that you may be pushing the resource limits in your plan. If this is the case, you should monitor the memory usage for several days to see if that number is consistent, or was just an anomaly due to peak load condition.

Adjusting the Java 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/jboss7/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.

The following must be done from the command line of the VS. See the User Guide: Connecting to your Virtual Server (SSH and MindTerm) http://support.eapps.com/ispmgr/ssh for more information if needed.

[root@eapps-example ~]# cd /etc/jboss7
[root@eapps-example jboss7]# vim jboss.conf

Using a text editor (in this example the vim editor), edit the jboss.conf file and change the settings below to your desired heap size values.

The default values for the Java Heap Size are 512 MB for Initial and 512 MB for Maximum. This is the same no matter which offering you have. You will generally need to adjust the wrapper.java.maxmemory upwards, and leave the wrapper.java.initmemory as is.

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

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

Make whatever changes are needed, and then save and exit the jboss.conf file. You will need to restart JBoss for the new Heap settings to take effect.