Installing and Configuring JBoss AS

Prerequisites

• Java
• XML
• Eclipse
• Batch scripting

Installing JBoss AS

1. Download and install the Java 1.5 SDK or higher.
2. Download the most recent stable binaries from http://www.jboss.org/jbossas/downloads/.
3. Unzip the files to the directory of your choice.
4. Create an environment variable called JBOSS_HOME that points to the directory. The command is: export PATH=$PATH:(yourDir).
5. JBoss AS is ready to be used.

Starting JBoss AS

At the command prompt, go to the JBOSS_HOME/bin/ directory and run the run.sh (Linux/Mac/Unix) or run.bat (Windows). You will then see a load of logging information. The JBoss AS will be completely up and running when you see something like:


at the command prompt. To verify that it is working properly, navigate in your favorite browser to http://servername:8080/, where servername is the name of the host.

Shut Down JBoss AS

At the command prompt, go to the JBOSS_HOME/bin/ directory and run shutdown.sh (Linux/Mac/Unix) or shutdown.bat (Windows).

Point Eclipse to APIs

If Eclipse does not recognize the portlets, servlets, log4j (basically most J2EE APIs and frameworks) fresh out of the box, they will need to be included in the build paths.

Portlets/Servlets/Logging APIs

1. Download the following APIs (there are alot more, but this is all Ive used so far):
   • portlet-api-1.0.jar
   • servlet-api.jar
   • log4j-1.2.15.jar (or most recent)
2. Open the Preferences dialog in Eclipse.
3. Expand the tree labeled Java.
4. Expand the sub-tree labeled Build Path.
5. Click on User Libraries.
6. Click New.
7. Provide appropriate name for the library, such as J2EE_Libs.
8. Select the newly created library and click on Add JARs.
9. Locate the jars downloaded from above.
10. Add each one to the library.
11. Click OK.
12. Right click on the project that requires the APIs, expand Build Path, and click on Configure Build Path. Alternatively, you may click on the Project menu and click on properties.
13. Click on Java Build Path from the menu.
14. Click on the Libraries tab.
15. Click on Add Library.
16. Select User Library from the list then click Next.
17. Checkmark the box next to the library that was just created and click Finish.
18. Click OK.
19. The project will have the libraries added.

Configuring Remote Debugging in Eclipse

JBoss AS Config:

1. Navigate to JBOSS_HOME/bin.
2. Open the run.conf (run.bat for windows) file for editing.
3. Add the following:
   
   In run.conf:

   # Remote debugging for Eclipse
   

   JAVA_OPTS="$JAVA_OPTS -Xdebug -Xnoagent -Xrunjdwp:transport=dt_socket,address=8787, server=y, suspend=n"
   
   
   after these lines:

   #
   # Specify options to pass to the Java VM.
   #
   if [ "x$JAVA_OPTS" = "x" ]; then
      JAVA_OPTS="-Xms128m -Xmx512m -Dsun.rmi.dgc.client.gcInterval=3600000 -Dsun.rmi.dgc.server.gcInterval=3600000"
   fi
   

   In run.bat:

   rem Enable remote debugging.
   set JAVA_OPTS= -Xdebug -Xnoagent -Xrunjdwp:transport=dt_socket,address=8787,server=y,suspend=y %JAVA_OPTS%

   after these lines:

   rem With Sun JVMs reduce the RMI GCs to once per hour
   set JAVA_OPTS=%JAVA_OPTS% -Dsun.rmi.dgc.client.gcInterval=3600000 -Dsun.rmi.dgc.server.gcInterval=3600000

4. Save the file.
5. The JBoss AS is now configured for remote debugging.

*Note: JBoss AS will need to be restarted for changes to take effect.

Eclipse Config:

1. Open the Preferences dialog in Eclipse.
2. Expand the Server tree and click on Installed Runtimes.
3. Click on Add.
4. Select the version of JBoss that is being used.
5. Make sure Also create new server is checked.
6. Click Next.
7. Select the JRE that JBoss will be running on.
8. Specify the directory where the JBoss files reside.
9. Click Next.
10. Specify the IP of the server. If running locally, use 127.0.0.1.
11. If you decided to change the port number for JBoss, be sure to change it here to match.
12. Use the defaults for the rest of the fields.
13. Click Finish.
14. Eclipse is now setup for remote debugging.

Configuring Startup Timeout

When starting from Eclipse, JBoss takes a little longer to boot. Eclipse will prevent it from starting completely if it takes too long (ie more than 50 seconds). It typically starts for me in 1 min 20 secs. To change the settings, follow these instructions:

1. Open Eclipse.
2. Go to Preferences.
3. Click on Server.
4. Change the option labled Server timeout delay: to Unlimited.
5. Click OK.

Configuring PermGen

Periodically when developing and redeploying web apps, an error will occur and the JBoss AS will crash, burn, and will require a restart. Most of the time, the error is an out of memory error and will appear in the console as follows:

10:10:22,640 ERROR [MainDeployer] Could not create deployment: file:(yourFile)
java.lang.OutOfMemoryError: PermGen space

To fix this you will need to modify the run file, again. There are two options: increase the size of the PermGen or allow garbage collection on PermGen . Each method has its pro/cons. Increasing the size of the PermGen will only delay the errors longer, because the memory will be used up eventually. If all you are looking to do is increase the time between restarts, this is a viable solution. If low memory is an issue or if the error must be prevented altogether, then garbage collection should be permitted on PermGen. With this solution, you may run the risk of garbage collecting classes that will be used again (this has not been tested). Both may be used which may lessen the risk that classes will be collected before their time. Realize that this does not eliminate the risk. Note that both methods will require JBoss AS to be restarted.

Increase Memory Size of PermGen:

1. Navigate to JBOSS_HOME/bin/.
2. Open the run.conf (run.bat for windows) file for editing.
3. Add the following after the remote debugging lines:
   
   In run.conf:

   # Memory configuration to delay PermGen: OutOfMemoryError(s)
   JAVA_OPTS="$JAVA_OPTS -XX:MaxPermSize=512m"

   In run.bat:

   rem Memory configuration to delay PermGen: OutOfMemoryError(s)
   set JAVA_OPTS=-XX:MaxPermSize=512m %JAVA_OPTS%

4. Save the file.
5. PermGen will be configured with a larger memory space.

*Note: A size other than 512 may be used.

Garbage Collection on PermGen

1. Navigate to JBOSS_HOME/bin/.
2. Open the run.conf (run.bat for windows) file for editing.
3. Add the following after the remote debugging lines:
   
   In run.conf:

   # Garbage Collection configuration to fix PermGen: OutOfMemoryError(s)
   JAVA_OPTS="$JAVA_OPTS -XX:+UseConcMarkSweepGC -XX:+CMSPermGenSweepingEnabled -XX:+CMSClassUnloadingEnabled"

   In run.bat:

   rem Garbage Collection configuration to fix PermGen: OutOfMemoryError(s)
   set JAVA_OPTS= -XX:+UseConcMarkSweepGC -XX:+CMSPermGenSweepingEnabled -XX:+CMSClassUnloadingEnabled %JAVA_OPTS%

4. Save the file.
5. PermGen will be configured to be garbage collected.

Application/Server Specific Configurations

Directories

As of JBoss 4.0.0, there are 3 folders/configurations that are supported:

1. default
2. minimal
3. standard

Each folder supports a different JBoss "configuration." The minimal will load the bare essentials for JBoss to run. The default is what is used when run.sh/run.bat is executed. It loads the most commonly used components in JBoss. This is the directory that will be used most often. Other configurations may be created. Just create your own folder, copy an existing config into it, and then modify it to your needs. To launch something other than default, use run.sh -c configuration, where configuration is the folder name. Replace run.sh with run.bat for Windows.

There are 4 directories in JBOSS_HOME/server/(yourConfigDir) that are of most concern in a J2EE App:

1. /conf
2. /deploy
3. /lib
4. /log

The /conf folder contains configuration files for the server. The /deploy folder is where .ear, .war, services, and data sources are stored. This folder is hot deployable, meaning anything placed here will automatically be detected by the AS. The /lib folder contains any necessary libraries/jar files for an application (such as the JDBC drivers). The /log folder contains all the logs for the JBoss configuration. The boot log, server logs, and application logs will be found here. Depending on the size of the hard drive, these logs will have to be periodically deleted. JBoss generates a massive amount of logs and will take up alot of space. These 4 folders will be in JBOSS_HOME/server/(yourConfigDir).

Configuring Hot Deploy

The JBoss AS automatically deploys .war, .ear, etc when they are dropped into the deploy directory. However, it may sometimes take up to a minute for JBoss to recognize that there was a change. For changes to occur almost instantaneously follow these instructions:

1. Navigate to JBOSS_HOME/server/(yourConfigDir)/conf
2. Open jboss-service.xml for editing.
3. Find the tags:

   <attribute name="ScanPeriod"></attribute>

4. The value should be something like 5000. Change this to 500.
5. Save the file.

*Note: If the change does not take effect, look for a file named jboss-yourConfigDir.xml and follow the rest of the directions.

This is ideal for a development server, however, with each hot deploy errors may occur. An example would be the state of a session if a user was connected. Additionally, JBoss seems to deteriorate after many hot deploys. You'll have to periodically restart the app server to fix this. This is not something that is recommended for a production environment. If one wishes to disable hot deploy, all they have to do is change the tags

<attribute name="ScanEnabled">true</attribute>

in jboss-service.xml to false.

Running JBoss as a Service

I recently came across a phenomenon on one of our production environments where JBoss would shutdown every night.  I would start the server using bin/run.sh -b 0.0.0.0 from a remote login and every time it would shutdown 30 minutes to 45 minutes after I left work.  I ascertained it was due to the remote session closing which also closes all child processes.  There are two solutions:

More on this later...