Level: Introductory William B. Zimmerly (bill@zimmerly.com), Freelance Writer and Knowledge Engineer
10 Oct 2006 Get a cookbook-style guide for downloading, installing, and configuring Apache Geronimo for productive use. A pinch of this and a dash of that, and viola! -- a state-of-the-art Java™ 2 Platform, Enterprise Edition (J2EE™)-certified server that's ready to dish out.
The dish of the month is Apache Geronimo, so get your kitchen organized and let's cook
up a feast. Every good cook has his or her secrets for setting up the kitchen. Let's
begin with the cooking area -- a good X-based Virtual Network Computing (VNC) server
(Xvnc) session on a server running Linux®.
 | | Not a chef? No worries. This article gives you step-by-step instructions on getting Geronimo up and running in minutes. And the nice thing is there won't be any dishes to clean up after you're done. |
|
Note: This article assumes that the server is running Red Hat Linux and that your
monitor's screen dimensions are 1024 x 768. File locations may differ on other versions
of Linux.
A good minimal setup for the cooking area is two xterm
windows along with a few other tools that make working under an
Xvnc session educational and fun. So with this in mind, perform the following steps:
- Fire up an
xterm window on the server, and change the
directory to $HOME/.vnc. There you'll find a file called xstartup.
- Rename this file
xstartup.original to preserve it, and then start your
favorite editor to create a new xstartup file with the contents shown in
Listing 1.
Listing 1. Contents of the xstartup file
#!/bin/sh
xterm -g 135x20+0+0 &
xterm -g 135x30+0+300 &
xclock -g +840+0 -digital -update 1 &
xclock -g +840+65 -update 1 &
xload -g +840+265 &
twm &
|
- Now run
vncserver to start the Xvnc
session, and minimize the server's xterm window. (You can use
any of several ways to make running this session more permanent, but they are beyond
the scope of this article.)
- Next, start the VNC viewer program on your computer, and connect to the server.
When the Xvnc session is running on your computer, the kitchen is set
up, and you're ready to assemble the ingredients. A good way to use the system is to use
the upper xterm window for .man files and other documentation, and use the larger lower xterm window for the work area in which
you execute the commands to install, build, and test the system.
The Java environment
After setting up the kitchen, you must download and install the one ingredient
common to both recipes: the Java Software Development Kit (SDK). You must be
running at least Java 1.4.2, which you can download from the Sun Microsystems
Web site (see Resources for a link). The file you need is
j2sdk-1_4_2_11-nb-5_0-linux.bin.
To install this file, you must become a superuser, make the file executable, and then
execute it. The code in Listing 2 outlines this process.
Listing 2. Install the Java SDK
$ su
Password: <root password>
# chmod +x j2sdk-1_4_2_11-nb-5_0-linux.bin
# ./j2sdk-1_4_2_11-nb-5_0-linux.bin
|
This code runs the installer; when it's finished, you'll have a nice Java toolkit
ready for building and testing Geronimo. However, you must perform one final step
before you can use the toolkit. Add the following lines to your $HOME/.bashrc
file so that they (1) force the shell to look in the toolkit for the updated Java
binaries and (2) define where the Geronimo code can locate the Java Runtime
Environment (JRE):
export PATH=/opt/j2sdk1.4.2_11/bin:$PATH
export JAVA_HOME=/opt/j2sdk1.4.2_11/jre
You can test to see whether all is correct by opening a new
xterm window and typing the commands shown in
Listing 3.
Listing 3. Test the Java SDK
$ java -version
java version "1.4.2_11"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.2_11-b06)
Java HotSpot(TM) Client VM (build 1.4.2_11-b06, mixed mode)
|
You should see the correct version listed as shown. If so, you're ready to start
cooking up a good helping of Geronimo.
Binary or source?
There are two basic methods for setting up Geronimo on a computer, each with its own
advantages and disadvantages. This article covers both methods and presents some of
the arguments for and against them. Each method is defined by the
starting point: binary or source. Although this article is primarily
concerned with installing Geronimo, the concepts are fairly universal no matter
what open source software package is the subject.
Binary installations, in general, are easier than source installations, because they
don't require source modules and spending computer resources compiling and linking
the code. They're also generally more frugal with disk space and can be simpler to
study.
Source installations, by contrast, can offer a valuable education on all the things
that programmers must do to code up and interface with the operating system using
the native tools of the programmer -- the compilers, linkers, and make and version
control tools. The source modules provide a resource for studying how Geronimo does
what it does and even provides ambitious programmers with a way to become part of
the Geronimo team by contributing bug fixes, new functionality, and perhaps new
examples or documentation.
Gather the ingredients
Every good cook knows to gather up the necessary ingredients up front. You can find all the ingredients you need on the Internet, and the specific URLs
for the various archives appear in Resources at
the end of this article. A binary installation of Geronimo requires the
geronimo-tomcat-j2ee-1.0.tar.gz file.
If, however, you're going to cook up Geronimo from source, you must have the
following files instead:
- subversion-1.3.2.tar.gz
- maven-1.0.2.tar.gz
- geronimo-1.0-src.tar.gz
Binary installation
Because the "distance" from start to finish in the binary installation is shorter,
involving only two ingredients -- Java technology and Geronimo -- it's the quickest
way to install a running version of Geronimo on your computer.
It's a good thing to have a source directory just beneath your home directory, and
by convention, this directory is typically called src. In this source
directory, you can install and build all the open source projects that interest you;
you can keep them all in a standard place so that you don't have to search far for
things you've built before. It's a standard practice in the open source community
to provide .tar file archives that, when you run them from the src directory,
install the project's home directory just beneath src, keeping things simple and
clean. Listing 4 shows the sequence in which to set up your
computer.
Listing 4. Sequence for creating the source directories
$ cd $HOME
$ mkdir src
$ cd src
$ mkdir geronimo
$ cd geronimo
$ mkdir binary
$ mkdir source
|
The intent is to install the binary installation to the src/geronimo/binary
directory and the source installation to the src/geronimo/source directory. Doing
so places the different builds close to each other and makes studying their
differences easier. Change to the binary directory, and then run the
tar command to build the directory tree within that
folder:
$ cd binary
$ tar -zxvf $HOME/downloads/geronimo-tomcat-j2ee-1.0.tar.gz
Voila! A binary installation of Apache Geronimo is ready for you to test.
Test the binary installation
If all has gone well with the installation, you can start Geronimo from an
xterm window by typing the following commands:
$ cd $HOME/geronimo/binary
$ java -jar bin/server.jar
After typing the command to start the Geronimo server, watch the output of the
xload application. This application charts the resources that the server uses
as Geronimo starts all of its functionality and the built-in deployed Web
applications.
When you see the text Geronimo Application Server Started, the server is
ready for testing. Open a Web browser, and then open the Web applications that
were installed with the binary installation package. The URL to start in is
http://<server>:8080/. After typing it, you should see the Welcome
page, which tells you that you've set up Geronimo successfully.
Get to know the package
From the Welcome page, you can click the Samples hyperlink and play with
various sample Web applications that come with the package. You can also see
the source code associated with each sample to learn more about how to use
Geronimo.
There are also links to the Geronimo home page and the project's wiki,
where people can collaborate on documenting and improving Geronimo. (Everyone
is welcome to contribute to the progress of the system.) Other important links
include the bug-tracking system and various subprojects of Geronimo.
When you're finished playing with the samples and exploring other links from the
binary installation, halt the server by making the xterm
window, in which you started Geronimo, current and then pressing Ctrl-C to start
the shutdown process.
Subversion and Maven
Assuming that you've already installed Java technology and the binary Geronimo
installation, you can move on to installing the tools that assist you in the
source installation. First, you need Apache Maven -- a software project-management
tool that automates the building, reporting, and documentation of the project.
After downloading the archive, install it in the src directory using the following command:
$ cd $HOME/src
$ tar -zxvf maven-1.0.2.tar.gz
Now add the following lines to your $HOME/.bashrc file so that the Maven
binary file can be found and it can find other files that it requires:
export MAVEN_HOME=$HOME/src/maven-1.0.2
export PATH=$HOME/src/maven-1.0.2/bin:$PATH
The next step is to create the local Maven repository by executing the following
script, which is included in the installation archive:
$ $MAVEN_HOME/bin/install_repo.sh $HOME/.maven/repository
Finally, start a new xterm session. Verify that Maven
is indeed installed properly by typing the following command on the command
line:
$ maven -v
The next ingredient to install is Subversion -- an open source version-control
system that the Apache Geronimo team uses to manage Geronimo modules. Use the
commands shown in Listing 5 to install and build Subversion.
Listing 5. Install and build Subversion
$ cd $HOME/src
$ tar -zxvf subversion-1.3.2.tar.gz
$ cd subversion-1.3.2
$ ./configure
$ make
$ su
Password: <root password>
# make install
# exit
|
To verify that Subversion was installed properly, type the following command:
$ svn --version
With both Maven and Subversion installed, you can proceed to installing the
Geronimo source and build the system with it.
The source module installation
Installing Geronimo from the source modules takes longer than the binary
installation process, but it's well worth it if you place a great deal of
importance on knowing your system well. When things go wrong or you
want to customize your setup, installing Geronimo from source is the best way to do
it. Use the following commands to extract the source archive:
$ cd $HOME/src/geronimo/source
$ tar -zxvf geronimo-1.0-src.tar.gz
From this point on, your computer must be connected to the Internet so that the
build process can download modules that were not included in the original source
module. The first command to execute completes a fresh checkout of the sources:
$ maven m:fresh-checkout
The fresh checkout takes some time to run, but when it's done, you should see a
Build Successful message. After this, execute the following command to build the
freshly checked-out modules:
$ maven new -Dmaven.test.skip=true -Dmaven.itest.skip=true
The system now builds all the Geronimo parts. Hopefully, you'll end up seeing another
Build Successful message when the system is done.
Conclusion
At this point, one cautionary note is in order. Because the Apache Geronimo project
is ongoing and the state of the modules and their repositories is in flux, failed
builds are the possible result of the source build instructions. Geronimo is a new
and collaborative effort involving multitudes of people. Thus, the method of automatic
source downloads with the build tools, rather than having static builds with no
download necessary beyond the initial package (as many other open source projects
use), can lead to problems. Geronimo is a fresh open source implementation of the
well-known J2EE standard, but a lot more work is still required. The bottom line?
Be patient -- the meal will be well worth it when it's properly prepared.
Resources Learn
Get products and technologies
Discuss
About the author | 
| | Bill Zimmerly is a knowledge engineer, a low-level systems programmer with expertise in various
versions of UNIX® and Microsoft® Windows® software, and a free thinker who worships at the altar of logic.
Creating new technologies and writing about them are Bill's passions. He resides in rural Hillsboro,
Missouri, where the air is fresh, the views are inspiring, and good wineries are all around. |
Rate this page
| 
