3.3. Custom Installation Procedure

To run the custom installation procedure, you'll need to download the installer package, which is an executable JAR. To start the install, run a command like this (using Java 1.4 or higher):

java -jar geronimo-1.0-M4-installer.jar

You should see the first screen of the installer:

Figure 3.1. Geronimo Installer: Welcome

Geronimo Installer: Welcome

Clicking Next brings up the license screen:

Figure 3.2. Geronimo Installer: License

Geronimo Installer: License

To proceed, select the I accept radio button and click Next to bring up the install path screen:

Figure 3.3. Geronimo Installer: Install Path

Geronimo Installer: Install Path

Select a path (by typing one in the box or selecting an existing directory with the Browse... button) and click Next to proceed. If the selected directory doesn't exist, you'll get one prompt:

Figure 3.4. Geronimo Installer: Create New Directory

Geronimo Installer: Create New Directory

Whereas if the directory does exist, you'll get a different prompt:

Figure 3.5. Geronimo Installer: Overwrite Existing Directory

Geronimo Installer: Overwrite Existing Directory

Generally speaking, it's best not to install the M4 release of Geronimo over top of a previous release. It's best to uninstall any previous release if desired, then install Geronimo M4 into a new directory.

After the directory select, the feature selection screen comes up:

Figure 3.6. Geronimo Installer: Feature Selection

Geronimo Installer: Feature Selection

There's generally no reason not to select all the features, since they add little space on top of the basic installation and even when installed they won't run unless manually started. The JMX Debug Tool is particularly useful as it's a simple web application you can start and browse to make sure the web container is up and running on the expected port.

Once the feature selection is complete, click Next to continue to the main configuration screen:

Figure 3.7. Geronimo Installer: Main Configuration

Geronimo Installer: Main Configuration

The default values are shown in Figure 3.7, “Geronimo Installer: Main Configuration”. The available fields are:

Username and Password

The administrative login for the server. This is primarily used by the deploy tool when it connects to a running server to deploy, start, or stop applications (see Section 10.4, “The Deploy Tool”). In future milestones, this will also be the account used to log in to the web-based management console.

Hostname

Several of the included services bind to a specific host name / IP when starting. The two most common values for this settings are localhost (meaning accept connections from the same machine only) and 0.0.0.0 (meaning bind to all available network interfaces). However, in a machine with multiple network interfaces, it's possible to specify a specific IP or hostname here to listen on that interface only.

HTTP Port

The network port that the web container listens on. This needs to be used in any HTTP URLs that refer to web applications running in Geronimo. Note that on UNIX platforms, you must run Geronimo as root to bind to privileged ports (under 1024), which is not recommend. To bind to port 80 (the default HTTP port), it would be better to run Geronimo behind an Apache web server where Apache listens on port 80 and Geronimo can listen on a non-privileged port.

HTTPS Port

The secure network port that the web container listens on. This needs to be used in any HTTPS URLs that refer to web applications running in Geronimo. Note that on UNIX platforms, you must run Geronimo as root to bind to privileged ports (under 1024), which is not recommend. To bind to port 443 (the default HTTPS port), it would be better to run Geronimo behind an Apache web server where Apache listens on port 443 and Geronimo can listen on a non-privileged port.

Security Port (to be added in Milestone 4)

The network port that the security system listens on. This is used for client authentication requests, and it must be configured in the client's JAAS configuration (see Chapter 14, Client Applications (Client JARs) [IN PROGRESS]).

Once the basic options are finished, click Next to proceed to the EJB/IIOP configuration screen:

Figure 3.8. Geronimo Installer: EJB/IIOP Configuration

Geronimo Installer: EJB/IIOP Configuration

The default values are shown in Figure 3.8, “Geronimo Installer: EJB/IIOP Configuration”. The available fields are:

Naming Port

The network port that the JNDI server listens on. Remote clients use this to connect to the server's JNDI tree. You'll need to customize your connection settings every time you run the deploy tool if you change this, so it's best to keep the default value of 1099.

EJB Port

The network port that the EJB container listens on. TODO: does this need to be configured in clients anywhere?

Clients

The IP addresses that the EJB server should accept connections from. TODO: is there a value for "any" and how do you specify a list or range?

IIOP Port

The port used to connect to EJBs via RMI-over-IIOP (as opposed to the plain RMI port listed under EJB Port above).

ORB Port

The port that the CORBA ORB listens on

CosNaming Port

The port that the CORBA naming service listens on. Similar to JNDI and RMI, a CORBA client will typically connect to the naming service first, then look up a specific service that it connects to using the ORB port.

Once the EJB/IIOP options are finished, click Next to proceed to the service configuration screen:

Figure 3.9. Geronimo Installer: Service Configuration

Geronimo Installer: Service Configuration

The default values are shown in Figure 3.9, “Geronimo Installer: Service Configuration”. The available fields are:

JMS Port

The network port that the default ActiveMQ JMS server listens on. This will need to be configured for any custom connection factories that should connect to that JMS server (a default connection factory is provided).

Derby Port

Geronimo includes an embedded Derby database used by the server itself. It is also available for use by applications, so it is configured for remote access, and this is the network port it listens on.

Once the service configuration options are set, click Next to proceed to the installation screen:

Figure 3.10. Geronimo Installer: Unpack Files

Geronimo Installer: Unpack Files

This screen unpacks all the raw Geronimo installation files. It doesn't quite result in a working installation, so when it finishes, click Next to continue to the customization screen:

Figure 3.11. Geronimo Installer: Customize Installation

Geronimo Installer: Customize Installation

This screen customizes the Geronimo installation according to the selected options. (Under the covers, it is building the startup JARs and deploying the core service configurations.) When it finishes, click Next to move on to the release notes:

Figure 3.12. Geronimo Installer: Release Notes

Geronimo Installer: Release Notes

Once you have finished with the release notes (which are also saved to the Geronimo installation directory), click Next to move on to the summary screen:

Figure 3.13. Geronimo Installer: Install Summary

Geronimo Installer: Install Summary

If you click the button to save an automatic installation script, you can repeat the installation (generally on a different machine) with an identical configuration. This option will prompt you to select a file to save the install script to. The install script is an XML file, though the file name is not important -- it just needs to be passed on the command line for an automated installation.

Once you click Done, Geronimo is ready to go!