2.2. Geronimo Quick Start

This section gives a fast-paced walkthrough of a simple installation and customization process for Geronimo. Each of the steps here is covered in more detail in subsequent chapters.

2.2.1. Download & Install

To begin with, download the .tar.gz or .zip package.

Unpack the Geronimo install package to create a new geronimo-1.0/ installation directory. On Windows, a tool like WinZip can be used to unpack the ZIP file. On Mac or Linux, a command like tar -xzvf geronimo-1.0-jetty.tar.gz can be used to unpack the TAR file. This results in the directory structure shown in Figure 2.1, “Quick Start: Install Directory” (see Chapter 3, Installing Geronimo [DRAFT (M4)] for more details).

Figure 2.1. Quick Start: Install Directory

Quick Start: Install Directory

2.2.2. Start the Server

Open a command prompt and change to the Geronimo installation directory. Make sure Java 1.4.2 is on the current PATH. To start the server, run the command java -jar bin/server.jar (see Section 3.6, “Starting the Server” for more details).

Figure 2.2. Quick Start: Startup Output

geronimo-1.0> java -jar bin/server.jar
Booting Geronimo Kernel (in Java 1.4.2_10)...
Starting Geronimo Application Server
[*************************] 100%  37s Startup complete
  Listening on Ports:
    1099   RMI Naming
    1389   Apache Directory LDAP
    1527   Derby Connector
    4201   ActiveIO Connector EJB
    4242   Remote Login Listener
    8019 Jetty Connector AJP13
    8080   Jetty Connector HTTP
    8443   Jetty Connector HTTPS
   61616   ActiveMQ Message Broker Connector

  Started Application Modules:
    EAR: geronimo/daytrader-derby-jetty/1.0/car
    EAR: geronimo/uddi-jetty/1.0/car
    EAR: geronimo/webconsole-jetty/1.0/car
    RAR: geronimo/activemq/1.0/car
    RAR: geronimo/system-database/1.0/car
    WAR: geronimo/jmxdebug-jetty/1.0/car
    WAR: geronimo/jsp-examples-jetty/1.0/car
    WAR: geronimo/ldap-demo-jetty/1.0/car
    WAR: geronimo/remote-deploy-jetty/1.0/car
    WAR: geronimo/servlets-examples-jetty/1.0/car
    WAR: geronimo/welcome-jetty/1.0/car

  Web Applications:

Geronimo Application Server started

Geronimo shows a text-based progress bar while it's starting, followed by a list of network ports it's listening on, applications that were started, and URLs to web applications that were started.

2.2.3. Customize Network Ports (if necessary)

The ports in Figure 2.2, “Quick Start: Startup Output” are the standard set for Geronimo. If any of them are already taken by other programs (for example, 8080 for Tomcat), stop Geronimo, edit the file var/config/config.xml and search for the port number that's a problem, replace it with a new port number, and start Geronimo again (see Chapter 5, Core Configuration [EMPTY] for more details). Figure 2.3, “Quick Start: Editing Ports in config.xml” shows a section of config.xml where the standard HTTP listen port of 8080 has been changed to 8180.

Figure 2.3. Quick Start: Editing Ports in config.xml

  <configuration name="geronimo/jetty/1.0/car">
    <gbean name="JettyWebConnector">
      <attribute name="host"></attribute>
      <attribute name="port">8180</attribute>
      <attribute name="redirectPort">8443</attribute>

2.2.4. Log in to Management Console

Once Geronimo has started, point a web browser to http://localhost:8080/console (or use the host name for the machine Geronimo is installed on, if not localhost). This brings up the login screen for the Geronimo management console:

Figure 2.4. Quick Start: Console Login

Quick Start: Console Login

Enter the username "system" and password "manager". The default administrator account is set in the files var/security/users.properties and var/security/groups.properties in the Geronimo installation (see Chapter 9, Security Configuration [DRAFT (1.0-pre)] for more details). Hit the Login button to start the console.

2.2.5. Create a Database Pool

The console has navigation options on the left, and a content area on the right.

Figure 2.5. Quick Start: Database Pools

Quick Start: Database Pools

To create a new database pool, Geronimo needs a JDBC driver. Geronimo ships with a JDBC driver for its embedded Apache Derby database, and can automatically download JDBC drivers for several popular open source databases (such as MySQL and PostgreSQL). For this quick start, we'll assume you create a Derby database pool, but you can also try configuring a pool pointing to a database of your own if you like (see Chapter 6, Database Configuration [DRAFT (1.0-pre)] for more details on creating custom database pools).


If you need to manually install a JDBC driver, create a directory named for the product under the repository/ directory and then a directory named jars/ under that, and copy the JDBC driver there (for example, for Oracle, create repository/oracle/jars/ and then copy the Oracle JDBC driver into there). For more information, see Section 6.1, “JDBC Drivers”.

To create a new Derby database:

  1. Select DB Manager in the navigation bar on the left.

  2. Enter TestDatabase in the Create DB field, and click the Create button.

  3. Make sure TestDatabase is listed in the Database List at the top of the screen.

To create a new database pool:

  1. Select Database Pools in the navigation bar on the left.

  2. Select the create pool Using the Geronimo database pool wizard link shown in Figure 2.5, “Quick Start: Database Pools”.

  3. Enter TestPool in the Name of Database Pool field, and select the database product from the Database Type drop-down (select Derby Embedded if you don't have a database of your own to connect to). Click the Next button to continue.

  4. Select the Driver JAR for your database. The drop-down shows encoded names for third-party JARs located in the repository/ directory of the Geronimo installation. For Derby, select org.apache.derby/derbyclient/ as the driver JAR. (If the server has Internet access and is not behind an HTML proxy server, you can use the Download a Driver button to automatically download many open source database drivers.)

  5. Enter other connection parameters to connect to the database. Many databases require a server name, database name, username, and password. (The embedded Derby driver does not require the server name, as it's always running in the same VM as the application server. You can also leave the username and password blank, though you should set the database name to, for example, TestDatabase.) Click the Next button to continue.

  6. On the next page, review the JDBC Connect URL that was generated, and if it looks okay, click Test Connection to try to connect to the database. If there are any problems, use the Edit Settings button to correct them, or else use the Deploy button to deploy the new database pool.


Derby lets you create a database on the fly by manipulating the connection URL, but due to a bug in Geronimo 1.0, it's not possible to configure this from the management console when the Tomcat web container is used (however, it does work in Jetty).

2.2.6. Create a Security Realm

After creating the database pool, run the following SQL script to create sample tables to use to create a SQL security realm:

create table TEST_USER (
    username varchar(20) not null primary key,
    password varchar(20) not null,
    name varchar(50));
create table TEST_USER_GROUPS (
    username varchar(20) not null,
    group_name varchar(20) not null,
    primary key (username, group_name));
insert into TEST_USER values ('jdoe','secret','John Doe');
insert into TEST_USER_GROUPS values ('jdoe','Employees');
insert into TEST_USER_GROUPS values ('jdoe','Administrators');

If you're using the embedded Derby database, you can select the DB Manager entry in the console to run the SQL script. Select TestDatabase under Use DB, paste the script above into the SQL Command/s window, and then click Run SQL.

The next step is to create a sample security realm. We'll create a SQL security realm based on the database pool created above (for more details on creating security realms, see Chapter 9, Security Configuration [DRAFT (1.0-pre)]). To create the new SQL security realm:

  1. Select Security Realms from the navigation area on the left side.

  2. Click the link to Add new security realm.

  3. Enter TestRealm for the Name of Security Realm and select Database (SQL) Realm as the Realm Type. Click Next to continue.

  4. Set the User SELECT SQL to select username, password from TEST_USER where username=? and set the Group SELECT SQL to select username, group_name from TEST_USER_GROUPS where username=?

  5. Select TestPool (or whatever you called the database pool above) as the Database Pool and click Next to continue (the other settings on this page are only used if no database pool is specified).

  6. Click Test a Login to make sure the realm is configured correctly.

  7. If you used the script above, enter jdoe as the Username and secret as the Password and click Next to test the login.

  8. If you used the script above and the jdoe login, the next screen should show that 3 principals were generated, one GeronimoUserPrincipal with name jdoe, one GeronimoGroupPrincipal with name Employees, and one GeronimoGroupPrincipal with name Administrators.

  9. Click Deploy Realm to deploy the new security realm.

2.2.7. Deploy Web Applications

This step walks through deploying a very simple web application (no additional configuration required), as well as a secure web application that needs to be hooked up to the security realm created in the previous step. If you have a simple web application (with no EJB references or resource references, etc.) to use as a test, you can try that (more details on the deployment options can be found in Chapter 10, Development & Deployment Overview [DRAFT (1.0)]), you can try that (and likewise, a simple web application that uses security but no resource references).

Otherwise, you can download a copy of the Geronimo Welcome web application and the Geronimo LDAP Demo web application (basically the same as you'd see at http://localhost:8080/ and http://localhost:8080/ldap-demo/ for a typical Geronimo install). The welcome application has no security and can be deployed as-is, while the LDAP demo application uses security so we can test the security realm created above. These applications are available at: http://cvs.apache.org/repository/geronimo/wars/geronimo-welcome-1.0-SNAPSHOT.war and http://cvs.apache.org/repository/geronimo/wars/geronimo-ldap-demo-1.0-SNAPSHOT.war.

First, you can try deploying the Welcome application with no additional Geronimo customization:

java -jar bin/deployer.jar deploy \

To make sure this is running, try connecting to http://localhost:8080/geronimo-welcome-1.0-SNAPSHOT/. This is a very small web app, so if the page comes up at all, then it worked (and that's all there is to see).

Next, create a geronimo-web.xml deployment plan that configures a custom URL prefix and security for the LDAP Demo web application. This web application is normally used to demonstrate the functionality of an LDAP security realm, but will work just as well to demonstrate the test realm created above. The plan should look like this (and see Chapter 11, Web Applications (WARs) [DRAFT (1.0)] for more details on the web application Geronimo deployment plan):

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://geronimo.apache.org/xml/ns/j2ee/web-1.0"
            <principal name="anonymous" class="org.
            <role role-name="content-administrator">
                <principal name="Administrators" class="org.

This plan:

  • Sets the web application to appear at a URL starting with /test-web

  • Sets the security system to run any logins against the TestRealm security realm.

  • Sets the default principal to a user named "anonymous" for pages where security is not required but the page still calls HttpServletRequest.getUserPrincipal.

  • Maps all users in the "Administrators" group in the security realm to the "content-administrators" J2EE role (which is declared in the web.xml for the LDAP Demo realm).


Make sure to remove the whitespace in the principal class names in the plan listed above (2 places). The fully-qualified class names are only split across lines in that listing to fit the margins of the book -- they won't really work if entered that way.

To deploy the LDAP demo web application with this plan, use a command like this:

java -jar bin/deployer.jar deploy \
    geronimo-ldap-demp-1.0-SNAPSHOT.war geronimo-web.xml

To test the security realm, try connecting to http://localhost:8080/test-web/. From the front page there, click the Protect link to force a login (and use the username "jdoe" and password "secret" if you set up the sample security realm using the SQL in this quick start). You can also try the Forbidden link to make sure that pages you can't access are properly rejected with a 403 error.

2.2.8. Quick Start Summary

That's it for the quick start. If you followed the whole thing, you:

  • Downloaded Geronimo

  • Installed Geronimo

  • Changed any conflicting network ports

  • Tried out the Geronimo management console

  • Created a database connection pool

  • Created a security realm based on the test database pool

  • Deployed a simple web application requiring no customization

  • Deployed a more complex web application, customizing it to use the test database pool and security realm

  • Tried a login to make sure everything worked

If there are certain areas in the quick start that you want to investigate in more detail, you can follow the cross-references in the text. Otherwise, the following chapters will introduce you to each of the features of Geronimo in more depth.