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

Unpack the Geronimo install package to create a new geronimo-1.1/ 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-jetty-j2ee-1.1.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 (1.1)] for more details).

Figure 2.1. Quick Start: Install Directory

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

geronimo-1.1> java -jar bin/server.jar
Booting Geronimo Kernel (in Java 1.5.0_07)...
Starting Geronimo Application Server v1.1
[************************] 100%  25s Startup complete
  Listening on Ports:
    1099 0.0.0.0 RMI Naming
    1527 0.0.0.0 Derby Connector
    4201 0.0.0.0 ActiveIO Connector EJB
    4242 0.0.0.0 Remote Login Listener
    8009 0.0.0.0 Jetty Connector AJP13
    8080 0.0.0.0 Jetty Connector HTTP
    8443 0.0.0.0 Jetty Connector HTTPS
    9999 0.0.0.0 JMX Remoting Connector
   61616 0.0.0.0 ActiveMQ Message Broker Connector

  Started Application Modules:
    EAR: geronimo/webconsole-jetty/1.1/car
    RAR: geronimo/activemq/1.1/car
    RAR: geronimo/system-database/1.1/car
    WAR: geronimo/remote-deploy-jetty/1.1/car
    WAR: geronimo/welcome-jetty/1.1/car

  Web Applications:
    http://remus:8080/
    http://remus:8080/console
    http://remus:8080/console-standard
    http://remus:8080/remote-deploy

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.

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.

...
  <module name="geronimo/jetty/1.1/car">
    <gbean name="JettyWebConnector">
      <attribute name="host">0.0.0.0</attribute>
      <attribute name="port">8180</attribute>
      <attribute name="redirectPort">8443</attribute>
    </gbean>
...

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

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)] for more details). Hit the Login button to start the console.

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

Figure 2.5. 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.1)] for more details on creating custom database pools).

	Tip
	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:

To create a new database pool:

	Tip
	Instead of creating the database in advance using the DB Manager, you can add ;create=true to the end of the JDBC URL that the console generates, and then the database will be created automatically when the connection pool is deployed.

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');

	Tip
	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)]). To create the new SQL security realm:

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://people.apache.org/repository/geronimo/wars/geronimo-welcome-1.1-SNAPSHOT.war and http://people.apache.org/repository/geronimo/wars/geronimo-ldap-demo-1.1-SNAPSHOT.war.

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

java -jar bin/deployer.jar deploy \
    geronimo-welcome-1.1-SNAPSHOT.war

To make sure this is running, try connecting to http://localhost:8080/geronimo-welcome-1.1-SNAPSHOT/. This is a very small web application, 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.1)] 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.1">
    <environment>
        <moduleId>
            <artifactId>TestWebApplication</artifactId>
        </moduleId>
    </environment>
    <context-root>/test-web</context-root>
    <security-realm-name>TestRealm</security-realm-name>
    <security>
        <default-principal>
            <principal name="anonymous" class="org.
apache.geronimo.security.realm.providers.GeronimoUserPrincipal"
            />
        </default-principal>
        <role-mappings>
            <role role-name="content-administrator">
                <principal name="Administrators" class="org.
apache.geronimo.security.realm.providers.GeronimoGroupPrincipal"
                />
            </role>
        </role-mappings>
    </security>
</web-app>

This plan:

	Warning
	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.1-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.

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

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.