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®.

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:

1. Fire up an xterm window on the server, and change the directory to $HOME/.vnc. There you'll find a file called xstartup.
2. 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.

#!/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 &

3. 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.)
4. 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.

$ 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.

$ 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.

Back to top

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

Back to top

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.

$ 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.

$ 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.

Back to top

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.

Back to top

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

• Download the Geronimo source and binary packages.
  
  
• Learn more about the J2EE standard.
  
  
• Check out the developerWorks Apache Geronimo project area for articles, tutorials, and other resources to help you get started developing with Geronimo today.
  
  
• Find helpful resources for beginners and experienced users at the Get started now with Apache Geronimo section of developerWorks.
  
  
• Check out the IBM® Support for Apache Geronimo offering, which lets you develop Geronimo applications backed by world-class IBM support.
  
  
• Visit the developerWorks Open source zone for extensive how-to information, tools, and project updates to help you develop with open source technologies and use them with IBM's products.
  
  
• Browse all the Apache articles and free Apache tutorials available in the developerWorks Open source zone.
  
  
• Browse for books on these and other technical topics at the Safari bookstore.
  
  
• See the Apache Geronimo wiki to learn more about Geronimo and contribute to the public pool of knowledge about this important technology.
  
  
• Stay current with developerWorks technical events and webcasts.
  
  

Get products and technologies

• Innovate your next open source development project with IBM trial software, available for download or on DVD.
  
  
• Download your free copy of IBM WebSphere® Application Server Community Edition V1.0 -- a lightweight J2EE application server built on Apache Geronimo open source technology that is designed to help you accelerate your development and deployment efforts.
  
  
• Download Java SDKs.
  
  
• Download Apache Maven 1.x.
  
  
• Download Subversion.
  
  

Discuss

• Get involved in the developerWorks community by participating in developerWorks blogs.
  
  

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.

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• The Java environment
• Binary or source?
• Binary installation
• The source module installation
• Conclusion
• Resources
• About the author
• Comments

Next steps from IBM

Rational Application Developer features provide the comprehensive Integrated Development Environment (IDE) used to develop J2EE applications requiring Servlets and JavaServer Pages (JSPs).

---

• Try: Try the free Rational Application Developer, which helps developers quickly design, develop, test, analyze, and deploy high-quality Java, Javaserver pages, and J2EE applications.
• Article: Learn how you can deliver accurate, higher-quality J2EE apps with Rational Application Developer, open source JUnit and JUnitEE test frameworks.
• Tutorial: Build a Facebook application using PHP, the Spring framework, and J2EE.
• Buy: Rational Application Developer

My developerWorks community

Dig deeper into Open source on developerWorks

Rate a product. Write a review.

Write a review for Rational products today!

Special offers