JBoss Application Server is the open source implementation of the Java EE suite of services. It comprises a set of offerings for enterprise customers who are looking for preconfigured profiles of JBoss Enterprise Middleware components that have been tested and certified together to provide an integrated experience. It's easy-to-use server architecture and high flexibility makes JBoss the ideal choice for users just starting out with J2EE, as well as senior architects looking for a customizable middleware platform.
Because it is Java-based, JBoss Application Server is cross-platform, easy to install and use on any operating system that supports Java. The readily available source code is a powerful learning tool to debug the server and understand it. It also gives you the flexibility to create customized versions for your personal or business use.
Installing JBoss Application Server is simple and easy. You can have it installed and running in no time. This guide will teach you to install and uninstall JBoss.
If you find a typographical error in the Installation Guide, or if you have thought of a way to make this manual better, we would love to hear from you! Please submit a report in JIRA: http://jira.jboss.com against the project JBoss Application Server and component Installation_Guide.
If you have a suggestion for improving the documentation, try to be as specific as possible when describing it. If you have found an error, please include the section number and some of the surrounding text so we can find it easily.
Note
Be sure to give us your name so you can receive full credit.
Note
This content is taken from svn.jboss.org/repos/jbossas/projects/docs/trunk and has yet to be branched.
To access the content directly and make changes yourself:
svn co https://svn.jboss.org/repos/jbossas/projects/docs/trunk --username yourname
You must have adequate disk space to install JDK and JBoss Application Server while also allowing enough space for your applications. Before installing JBoss Application Server you must have a working installation of Java. Since JBoss is 100% pure Java you can have it working on any Operating System / Platform that supports Java. However there are a few Operating System-specific issues that you must be aware of. Refer to http://wiki.jboss.org/wiki/Wiki.jsp?page=JBossOperatingSystemSpecificIssues for more information.
For the latest information on supported Operating System / JVM combinations and supported Database platforms, please refer to http://www.jboss.com.
You must have a working installation of JDK 1.5 before you install JBoss Application Server. You can install the 32-bit or 64-bit JVM as per your requirements. In this guide we will show you how to install a 32-bit Sun JDK 5.0 on a Linux Platform and Microsoft Windows Platform. But before we do that let's take a look at some of the benefits of using a 64-bit JVM.
Benefits of 64-bit JVM on 64-bit OS and Hardware:
Wider datapath: The pipe between RAM and CPU is doubled, which improves the performance of memory-bound applications.
64-bit memory addressing gives virtually unlimited (1 exabyte) heap allocation. However large heaps affect garbage collection.
Applications that run with more than 1.5GB of RAM (including free space for garbage collection optimization) should utilize the 64-bit JVM.
Applications that run on a 32-bit JVM and do not require more than minimal heap sizes will gain nothing from a 64-bit JVM. Barring memory issues, 64-bit hardware with the same relative clock speed and architecture is not likely to run Java applications faster than their 32-bit cousin.
Installing and Configuring 32-bit Sun JDK 5.0 on Linux
Download the Sun JDK 5.0 (Java 2 Development Kit) from Sun's website: http://java.sun.com/javase/downloads/index_jdk5.jsp. Choose "JDK 5.0 Update <x>" (where x is the latest update number) for download and then select "RPM in self-extracting" file for Linux[1]. Read the instructions on Sun's website for installing the JDK.
If you don't want to use SysV service scripts you can install the "self-extracting file" for Linux instead of choosing the "RPM in self-extracting" file. In that case you can skip the next step mentioned here. But it is recommended to use the SysV service scripts for production servers.
Download and install the appropriate
-compat RPMfromJPackagehere. Please ensure you choose a matching version of the-compatpackage to the JDK you installed.Create an environment variable that points to the JDK installation directory and call it
JAVA_HOME. Add$JAVA_HOME/binto the system path to be able to runjavafrom the command line. You can do this by adding the following lines to the.bashrcfile in your home directory.#In this example /usr/java/jdk1.5.0_14 is the JDK installation directory. export JAVA_HOME=/usr/java/jdk1.5.0_14 export PATH=$PATH:$JAVA_HOME/bin
Set this variable for the user account doing the installation and also for the user account that will run the server.
If you have more than one version of JVM installed in your machine, make sure you are using the JDK1.5 installation as the default source for the
javaandjavacexecutables. You can do this using the alternatives system. The alternatives system allows different versions of Java, from different sources to co-exist on your system.Select alternatives for java, javac and java_sdk_1.5.0
As root, type the following command at the shell prompt and you should see something like this:
[root@vsr ~]$ /usr/sbin/alternatives --config java There are 2 programs which provide 'java'. Selection Command ----------------------------------------------- 1 /usr/lib/jvm/jre-1.4.2-gcj/bin/java *+ 2 /usr/lib/jvm/jre-1.5.0-sun/bin/java Enter to keep the current selection[+], or type selection number:
Make sure the Sun version [
jre-1.5.0-sunin this case] is selected (marked with a '+' in the output), or select it by entering its number as prompted.Repeat the same for javac and java_sdk_1.5.0.
[root@vsr ~]$ /usr/sbin/alternatives --config javac There are 1 programs which provide 'javac'. Selection Command ----------------------------------------------- *+ 1 /usr/lib/jvm/java-1.5.0-sun/bin/javac Enter to keep the current selection[+], or type selection number:
[root@vsr ~]$ /usr/sbin/alternatives --config java_sdk_1.5.0 There are 1 programs which provide 'java_sdk_1.5.0'. Selection Command ----------------------------------------------- *+ 1 /usr/lib/jvm/java-1.5.0-sun Enter to keep the current selection[+], or type selection number:
You should verify that java, javac and java_sdk_1.5.0 all point to the same manufacturer and version.
Note
You can always override this step by setting the
JAVA_HOMEenvironment variable as explained in the previous step.Make sure that the
javaexecutable is in your path and that you are using an appropriate version. To verify your Java environment, typejava -versionat the shell prompt and you should see something like this:[root@vsr ~]$ java -version java version "1.5.0_14" Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_14-b03) Java HotSpot(TM) Client VM (build 1.5.0_14-b03, mixed mode, sharing)
Installing and Configuring 32-bit Sun JDK 5.0 on Microsoft Windows
Download the Sun JDK 5.0 (Java 2 Development Kit) from Sun's website: http://java.sun.com/javase/downloads/index_jdk5.jsp. Choose "JDK 5.0 Update <x>" (where x is the latest update number) for download and then select your Windows Platform options to perform the installation.
Create an environment variable called
JAVA_HOMEthat points to the JDK installation directory, for example:C:\Program Files\Java\jdk1.5.0_14\. In order to run java from the command line add thejre\bindirectory to your path, for example:C:\Program Files\Java\jdk1.5.0_14\jre\bin. To do this, open the Control Panel from the Start Menu, switch to Classic View if necessary, open the System Control Panel applet, select the Advanced Tab, and click on the Environment Variables button.
You can install the JBoss Application Server in one of these two modes:
Binary files download
In this form of installation, simply unzip the downloaded zip file to the directory of your choice. You can unzip the JBoss Application Server on any operating system that supports the zip format. The zip file is available on http://labs.jboss.com/jbossas/downloads/. Please ensure you have met the pre-requisites required before proceeding with your installation. Pre-requisites are discussed in Section 1.1, “Pre-Requisites”. Further details on installation using the Binary files are discussed in Chapter 3, Installation With Binary Download
Source Files download
In this form of installation, download the source files from the web and build the source files locally. On successfully building your source files you can manually copy the built file into a desired folder and start the server. Please ensure you have met the pre-requisites required before proceeding with your installation. Pre-requisites are discussed in Section 1.1, “Pre-Requisites”. For more instructions on building your source files, please refer to Chapter 4, Installation With Source Download.
Four types of server configurations will be included in your installation - minimal, default, and all. The Getting Started Guide explains in detail the different server configuration file sets.
You can download the Binary zip file from http://labs.jboss.com/jbossas/downloads/.
In this form of installation, simply unzip the downloaded zip file to the directory of your choice on any operating system that supports the zip format.
Unzip
jboss-4.2.2.GA.zipto extract the archive contents into the location of your choice. You can do this using the JDKjartool (or any other ZIP extraction tool). In the example below we are assuming you downloaded the zip file to the/jbossdirectory.[usr]$
cd /jboss[usr]$jar -xvf jboss-4.2.2.GA.zipYou should now have a directory called
jboss-4.2.2.GA. Next you need to set your JBOSS_HOME environment variables. This is discussed in Chapter 5, Setting the JBOSS_HOME variable.
You can download the zip source file from http://labs.jboss.com/jbossas/downloads/.
Uncompress
jboss-4.2.2.GA-src.tar.gzto extract the archive contents into the location of your choice. You can do this using the JDKjartool (or any other compatible extraction tool). In this example we are assuming your source files were copied in the/jbossfolder.[user@localhost]$ cd /jboss [user@localhost]$ jar -xvf jboss-4.2.2.GA-src.tar.gz
You should now have a directory called
jboss-4.2.2.GA-src. The next step is to build your source files. In this example we are using Apache ANT. This is discussed in the following section.
Apache Ant is a Java-based build tool. Instead of using an extended model using shell-based commands, Ant is extended using Java classes that uses XML-based configuration files. The configuration files call out a target tree that executes various tasks. Each task is run by an object that implements a particular Task interface. This gives you the ability to perform cross platform builds. Please also note that if needed, Ant provides an <exec> task that allows commands to be executed based on the Operating System it is executing on. For more information on Apache ANT please click here.
You will need to build your JBoss Application Server source files before you can run the application server. Firstly please download and install Apache Ant version 1.5 or 1.6 from the Apache Ant Archive. Apache Ant versions 1.5 and 1.6 have been tested on JBoss Application Server 4.2.2. Version 1.7 is not compatible and will give the following error if used.
[user@localhost]$ cd jboss/jboss-4.2.2.GA-src/build [user@localhost build]$ ant Buildfile: build.xml check.inhibit.downloads: check.proxy: set.proxy.withoutauth: ... BUILD FAILED /jboss/jboss-4.2.2.GA-src/tools/etc/buildmagic/buildmagic.ent:28: Unsupported Ant version: Apache Ant version 1.7.0 compiled on December 13 2006 Please install a version which is compatible with Ant 1.5 or 1.6. Total time: 0 seconds
On downloading ANT, please unzip the compressed file and copy to the desired location. Like Java, you also need to set the environment variables for Apache ANT. The following example illustrates a desirable configuration for the .bashrc file. In the example the file is edited using the gnome text editor (gnome).
[user@localhost ~]$ gedit .bashrc # Source global definitions if [ -f /etc/bashrc ]; then /etc/bashrc fi ...... # User specific aliases and functions # The following are the environment variables for Java, ANT and JBoss export JAVA_HOME=/usr/java/jdk1.5.0_14 export PATH=$PATH:$JAVA_HOME/bin export ANT_HOME=/usr/ant/apache-ant-1.6.0 export PATH=$PATH:$ANT_HOME/bin
To implement the changes you've made to the .bashrc file, type the following on a terminal.
[user@localhost ~]$ source .bashrc [user@localhost ~]$
If any errors are displayed, please check your .bashrc file for errors and ensure that all directory paths are correct.
To build the JBoss Application Server source files with Apache ANT, from a terminal change directory to where the unzipped source files are. In the following example we are assuming that the source files were copied and unzipped in the logged in user's downloads folder.
[user@localhost]$ cd /home/user/downloads/jboss-4.2.2.GA-src/build [user@localhost build]$ ls build.bat build.log build.sh build.xml eclipse.psf local.properties VersionRelease.java build-distr.xml build-release.xml build-thirdparty.xml docs etc output
From the contents of the build directory above, you can see the build.xml file which is used by Apache ANT as a configuration file when building your source files. The next step is to perform the build using Apache ANT as illustrated below.
[user@localhost build]$ ant compile-classes: [mkdir] Created dir: /jboss/jboss-4.2.2.GA-src/tomcat/output/classes [javac] Compiling 89 source files to /jboss/jboss-4.2.2.GA-src/tomcat/output/classes .... ....content truncated ..... ..... _buildmagic:build-bypass-check: jars: most: main: BUILD SUCCESSFUL Total time: 2 seconds
A successful build will have the above message. If your build fails, please check the error log and ensure that your configuration files and environment variables are correctly set. The JBoss Application Server files are built under the build/jboss-4.2.2.GA directory as indicated below.
[user@localhost build]$ ls build.bat build.log build.sh build.xml eclipse.psf jboss-4.2.2.GA local.properties VersionRelease.java build-distr.xml build-release.xml build-thirdparty.xml docs etc outputjboss-4.2.2.GA [user@localhost build]$ cd jboss-4.2.2.GA [user@localhost build]$ ls bin client docs lib server
The jboss-4.2.2.GA contains your successful JBoss Application Server files. You can copy this folder to a different location or run the server from this folder after setting the JBOSS_HOME environment variable in your .bashrc file. Next you need to set your JBOSS_HOME environment variables. This is discussed in Chapter 5, Setting the JBOSS_HOME variable.
Before you can run the JBoss Application Server, you need to ensure that you've configured the JBOSS_HOME environment variable in your .bashrc file as follows. In this example the Application Server folder has beeen copied to the /usr/jboss/jboss-4.2.2.GA folder. The following is a .bashrc file used in this installation. Please ensure that your .bashrc file has a similar configuration.
[user@localhost ~]$ gedit .bashrc # Source global definitions if [ -f /etc/bashrc ]; then /etc/bashrc fi ...... # User specific aliases and functions # The following are the environment variables for Java, ANT and JBoss export JAVA_HOME=/usr/java/jdk1.5.0_14 export PATH=$PATH:$JAVA_HOME/bin export ANT_HOME=/usr/ant/apache-ant-1.6.0 export PATH=$PATH:$ANT_HOME/bin export JBOSS_HOME=/usr/jboss/jboss-4.2.2.GA export PATH=$PATH:$JBOSS_HOME/bin
To implement your .bashrc file changes run the following command.
[user@localhost ~]$ source .bashrc [user@localhost ~]$
If no errors are displayed on your terminal, you are now ready to run your JBoss Application Server.
Create an environment variable called
JBOSS_HOMEthat points to the JBoss Application Server installation directory, for example:C:\Program\Files\JBoss\jboss-4.2.2.GA\.In order to run JBoss Application Server from the command line, add the
jboss-4.2.2.GA\bindirectory to your path, for example:C:\Program Files\JBoss\jboss-4.2.2.GA\bin. To do this, open the Control Panel from the Start Menu, switch to Classic View if necessary, open the System Control Panel applet, select the Advanced Tab, and click on the Environment Variables button.
You are now ready to start the JBoss Application Server. For more information on starting or stopping the server, please refer to Getting Started Guide.
The JBoss Application Server may be uninstalled by simply deleting the JBoss Application Server's installation directory. You will also need to remove the JBOSS_HOME environment variables discussed in Chapter 5, Setting the JBOSS_HOME variable for your Linux or Windows platform.
After you have installed the JBoss Application Server, it is wise to perform a simple startup test to validate that there are no major problems with your Java VM/operating system combination. To test your installation, move to JBOSS_DIST/jboss-as/bin directory and execute the run.bat (for Windows) or run.sh (for Linux) script, as appropriate for your operating system.
[vrenish@vinux bin]$ ./run.sh =====================================================
Note
Note that there is no "Server Started" message shown at the console when the server is started using the default profile, which is the default profile used when no other is specified. You may run the production This message may be observed in the server.log file located in the server/defaut/log subdirectory.
Now open http://localhost:8080 in your web browser. (Make sure you dont have anything else already on your machine using that port).[2] The contents of your page should look similar to this: Figure 7.1, “Test your Installation”.
You are now ready to use the JBoss Application Server. Refer to the Getting Started Guide for more information about the Server layout and example applications showcasing JBoss in action.
[2] Note that on some machines, the name localhost won’t resolve properly and you should use the local loopback address 127.0.0.1 instead.
| Revision History | |||
|---|---|---|---|
| Revision 4.2.2-1 | Oct 15 2007 | Michael Hideo <mhideo@redhat.com> | |
| |||