10.4. The Deploy Tool

Geronimo ships with a deploy tool capable of deploying both application modules and services. This section looks at the tool its capabilities, and its syntax.

The deploy tool is an executable JAR, located at bin/deployer.jar relative to the Geronimo installation directory. If you run it with no arguments, it'll give you a message with the basic syntax:

java -jar ...geronimo/bin/deployer.jar

Note that you can run the deploy tool from any directory; you needn't change to the Geronimo directory to use it. However, you cannot actually move its JAR, since it depends on other libraries in certain relative locations.

10.4.1. Deploy Tool Capabilities

The deploy tool connects to a running server (it does not work unless the server is available). The command-line deploy tool can:

  • Store login information for a particular server, so it doesn't need to be provided for every future call

  • Distribute an application (validate it and install it as an available server configuration)

  • Start an available server configuration that is not running

  • Stop a server configuration that is running (it will still be available)

  • Deploy an application (distribute it and start it)

  • Undeploy a server configuration (stop it if it's running, and remove it from the server environment altogether)

  • Redeploy a server configuration that is running (the old version will be stopped, a new version distributed, and the new version started)

  • List the configurations available in the server, either started, stopped, or both.

  • List the targets available to deploy to (useful for a server with multiple configuration stores, though that is quite rare).

10.4.2. Deploy Tool Concepts

The deploy tool terminology revolves around the J2EE Application Deployment specification (JSR-88). The specific terms as they apply to Geronimo are:

Module

The application module to be deployed. For example, an EAR or WAR file, or an exploded directory laid out the same way. Normally there is no module when deploying a Geronimo service. Once deployed, a module becomes a Geronimo server configuration.

ModuleID

The configId that uniquely identifies a deployed module (aka a server configuration). This is set in the Geronimo deployment descriptor for the module.

Target

A place that a module can be installed to. In some products this represents a server or a cluster. Geronimo doesn't have clusters, but it can actually have multiple configuration stores to install applications to (though this is rare). Each target corresponds to a single Geronimo configuration store. For more information, see Section 19.1, “The Configuration Store”.

TargetModuleID

Since the same module could be deployed to more than one target, a TargetModuleID uniquely identifies a deployed module by naming both the module and the target it is deployed to. It consists of the target name plus the ModuleID for the module.

(Deployment) Plan

A Geronimo deployment plan for a module. If maintained outside the server, it can be passed to the deploy tool on the command line. If packaged inside an application module, no plan argument is typically necessary.

10.4.3. Deploy Tool Syntax

The deploy tool has a common set of options governing how it connects to the server, then a variety of commands, and then specific options and arguments for each command. The basic structure of a deploy command looks like this:

java -jar deployer.jar [common opts] command [specific opts]

The next section discusses the common options, and the following sections address each of the available commands in detail.

10.4.3.1. Common Options: Login and Server Identification

If no common options are specified, the tool will attempt to connect to a running Geronimo server, on the standard management port, on the local machine. If you want to connect to a server running on a different port (or even to a J2EE 1.4 server other than Geronimo), you need to use some of these options. As well, the tool will prompt you for a username and password by default, but you can avoid that by logging so the tool saves your account information, or by specifying them as options on the command line.

--uri uri

Specifies a URI to connect to the server. This is formatted according to the JSR-88 (J2EE Deployment API) rules. A URI for Geronimo looks like: deployer:geronimo:jmx:rmi:///jndi/rmi://host:port/JMXConnector where the host and port fields identify the server to connect to (for example, the default host:port would be localhost:1099).

--host hostname

The host and port options can be used to connect to a Geronimo server other than localhost:1099, instead of specifying the full URI as above. This is just a shortcut to save typing the entire URI, but it doesn't work with servers other than Geronimo.

--port portnumber

A custom port number, typically used with --host instead of specifying the full URI to connect to a remote server o a server on an alternate port.

--driver jarfile

This tool can connect to any JSR-88-compliant server. To connect to a server other than Geronimo, pass the JSR-88 driver JAR file name to the deploy tool using this option.

--user username

If the server requires a username to connect (and Geronimo does), you can pass it on the command line using this option. In the case of Geronimo, you'll be prompted for a username if you don't supply it and it's necessary. For other servers, you always need to specify it on the command line. (The default user for Geronimo is "system".)

--password password

If the server requires a password to connect (and Geronimo does), you can pass it on the command line using this option. In the case of Geronimo, you'll be prompted for a password if you don't supply it and it's necessary. For other servers, you always need to specify it on the command line. (The default password for Geronimo is "manager".)

--syserr

Log all exceptions to System.err.

--verbose

Add full stack traces to any error messages generated during a deployment operation.

So in the normal case, you can specify none of these, and you'll connect to a running Geronimo server on localhost, and the deploy tool will prompt you for a username and password. Note that the username and password are configured in the user and group properties files in geronimo/var/security, unless you have replaced the default security realm.

10.4.3.2. Help Command

The help command gives help on the deploy tool, the common options, an individual command, or all commands. It looks like this:

java -jar deployer.jar help
java -jar deployer.jar help options
java -jar deployer.jar help [command]
java -jar deployer.jar help all

The help command does not attempt to connect to the server, so the common options are ignored when requesting help.

10.4.3.3. Login Command

The login command collects your authentication information for a specific server connection, and stores it to the file .geronimo-deployer in your home directory. That way, any commands given for that same server will read the saved information instead requiring the username and password to be specified each time. The information in this file is not stored in plain text, but it is not secure against an attacker, so it's best to restrict read access to that file. It looks like this:

java -jar deployer.jar login
java -jar deployer.jar --host test-server.company.com login

The login command does actually connect to the remote server in order to validate the login.

10.4.3.4. Deploy Command

The deploy command validates an application module or service, installs it into the server environment, and starts it. It takes a module and/or a plan as arguments (one or both must be provided). For example:

java -jar deployer.jar deploy web-app.war

That command would assume that the web application WAR had a Geronimo deployment descriptor packaged inside it (or else was so simple it didn't need one).

The deploy command can take a custom option listing the targets to deploy to:

--targets one;two;three...

Deploy the module to the specified targets. This is not usually necessary, since almost all Geronimo configurations have only one target (the single configuration store defined for the server).

A more complex deploy command would look like this (bearing in mind that the middle 3 lines should really be combined into one long name for the target):

java -jar deployer.jar deploy --targets \
  geronimo.server:J2EEApplication=null,
  J2EEModule=geronimo/j2ee-system/1.0/car,J2EEServer=geronimo,
  j2eeType=ConfigurationStore,name=Local \
  web-app.war web-plan.xml

The deploy command only works when the server is running.

10.4.3.5. Redeploy Command

The redeploy command assumes that a configuration is already running, and should be replaced by a newer version. This command takes the updated module and/or Geronimo deployment plan, and a list of the existing configurations that should be replaced. Usually this will be exactly one configuration name. However, you can pass more configuration names, or explicit target/configuration combinations if you like. The command typically looks like this:

java -jar deployer.jar redeploy web-app.war MyWebApp

In that case it would replace the configuration named MyWebApp with a newer version defined by the provided WAR.

If you want to identify a specific module on a specific target, you can use the syntax Target|Module, which is known as a TargetModuleID. A command with a TargetModuleID might look like this (bearing in mind that all the lines after the first should really be combined into one target name):

java -jar deployer.jar redeploy web-app.war \
  geronimo.server:J2EEApplication=null,
  J2EEModule=geronimo/j2ee-system/1.0/car,J2EEServer=geronimo,
  j2eeType=ConfigurationStore,name=Local|MyWebApp

The redeploy command only works when the server is running.

10.4.3.6. Start Command

The start command assumes that a configuration is available but not running; for example, it has been distributed but not started, or deployed and then subsequently stopped. This command will start the configuration, without making any other changes. This command takes a list of the existing configurations that should be started. Usually this will be exactly one configuration name. However, you can pass more configuration names, or explicit target/configuration combinations if you like. The command typically looks like this:

java -jar deployer.jar start MyWebApp

In that case it would start the configuration named MyWebApp.

If you want to identify a specific module on a specific target, you can use the syntax Target|Module, which is known as a TargetModuleID. A command with a TargetModuleID might look like this (bearing in mind that all the lines after the first should really be combined into one target name):

java -jar deployer.jar start \
  geronimo.server:J2EEApplication=null,
  J2EEModule=geronimo/j2ee-system/1.0/car,J2EEServer=geronimo,
  j2eeType=ConfigurationStore,name=Local|MyWebApp

The start command only works when the server is running.

10.4.3.7. Stop Command

The stop command assumes that a configuration is already running; for example, it has been previously deployed. This command will stop the configuration, but leave it available on the server. This command takes a list of the existing configurations that should be stopped. Usually this will be exactly one configuration name. However, you can pass more configuration names, or explicit target/configuration combinations if you like. The command typically looks like this:

java -jar deployer.jar stop MyWebApp

In that case it would stop the configuration named MyWebApp.

If you want to identify a specific module on a specific target, you can use the syntax Target|Module, which is known as a TargetModuleID. A command with a TargetModuleID might look like this (bearing in mind that all the lines after the first should really be combined into one target name):

java -jar deployer.jar stop \
  geronimo.server:J2EEApplication=null,
  J2EEModule=geronimo/j2ee-system/1.0/car,J2EEServer=geronimo,
  j2eeType=ConfigurationStore,name=Local|MyWebApp

The stop command only works when the server is running.

10.4.3.8. Undeploy Command

The undeploy command will stop an existing configuration (if necessary) and then remove it from the server environment. Once undeployed, a configuration cannot be started any more -- it must be distributed or deployed again first. This command takes a list of the existing configurations that should be undeployed. Usually this will be exactly one configuration name. However, you can pass more configuration names, or explicit target/configuration combinations if you like. The command typically looks like this:

java -jar deployer.jar undeploy MyWebApp

In that case it would undeploy the configuration named MyWebApp.

If you want to identify a specific module on a specific target, you can use the syntax Target|Module, which is known as a TargetModuleID. A command with a TargetModuleID might look like this (bearing in mind that all the lines after the first should really be combined into one target name):

java -jar deployer.jar undeploy \
  geronimo.server:J2EEApplication=null,
  J2EEModule=geronimo/j2ee-system/1.0/car,J2EEServer=geronimo,
  j2eeType=ConfigurationStore,name=Local|MyWebApp

The undeploy command only works when the server is running.

10.4.3.9. Distribute Command

The distribute command validates an application module or service and installs it into the server environment without starting it. It takes a module and/or a plan as arguments (one or both must be provided). For example:

java -jar deployer.jar distribute web-app.war

That command would assume that the web application WAR had a Geronimo deployment descriptor packaged inside it (or else was so simple it didn't need one).

The distribute command can take a custom option listing the targets to deploy to:

--targets one;two;three...

Distribute the module to the specified targets. This is not usually necessary, since almost all Geronimo configurations have only one target (the single configuration store defined for the server).

A more complex distribute command would look like this (bearing in mind that the middle three lines should really be combined into one target name):

java -jar deployer.jar distribute --targets \
  geronimo.server:J2EEApplication=null,
  J2EEModule=geronimo/j2ee-system/1.0/car,J2EEServer=geronimo,
  j2eeType=ConfigurationStore,name=Local \
  web-app.war web-plan.xml

The distribute command works regardless of whether the server is running.

10.4.3.10. List Modules Command

The list-modules command lists the available configurations on a server. If the --started option is specified then only running modules are displayed, if the --stopped option is specified then only non-running modules are displays, and otherwise all modules are displayed. For example:

java -jar deployer.jar list-modules --started

The list-modules command can also take a list of targets, and it will list modules specifically for those targets. This is usually not necessary, since almost all Geronimo configurations have only one target (the single configuration store defined for the server). A more complex list-modules command would look like this (bearing in mind that the lines after the first should really be combined into one target name):

java -jar deployer.jar list-modules --started \
  geronimo.server:J2EEApplication=null,
  J2EEModule=geronimo/j2ee-system/1.0/car,J2EEServer=geronimo,
  j2eeType=ConfigurationStore,name=Local

The list-modules command only works when the server is running.

10.4.3.11. List Targets Command

The list-targets command lists the available targets for a server. Usually, there will only be one. The command looks like this:

java -jar deployer.jar list-targets

The list-targets command only works when the server is running.

10.4.4. Remote Deployment

The deploy tool can connect to a remote server, or a server listening on a non-standard RMI port. The connectivity required is:

Local Server

  • RMI port (default 1099)

  • Shared filesystem (server process can read files generated by deploy tool)

Remote Server

  • RMI port (default 1099)

  • HTTP(s) port (default 8080)

  • Server running remote-deploy web application (which is running by default in Geronimo)

In the local environment, the client specifies file names and the server deploys by reading from those files. In the remote environment, the client uploads necessary files to the server, which saves them as temporary files and then deploys by reading those temp files.

[Tip]Tip

If there is a firewall between the deploy tool client and server, it must allow both ports 1099 and 8080 through from the client to the server (or the listen ports need to be changed accordingly).

10.4.5. Deploy Tool Troubleshooting

The deploy tool communicates with server-side components started in the geronimo/geronimo-gbean-deployer/1.0/car and geronimo/j2ee-deployer/1.0/car configurations. Therefore those configuration must be running (and they generally are) or the deploy tool will produce errors:

Missing j2ee-deployer:

Error: Unable to distribute geronimo-welcome-1.0.war: Cannot deploy
the requested application module
(moduleFile=/tmp/geronimo-deployer44619.tmpdir/geronimo-welcome-1.0.war)

Missing geronimo-gbean-deployer:

Error: Unable to distribute geronimo-welcome-1.0.war: No Deployer
GBean present in running Geronimo server. This usually indicates a
serious problem with the configuration of your running Geronimo
server.  If the deployer is present but not started, the workaround
is to run a deploy command like 'start
geronimo/geronimo-gbean-deployer/1.0/car'.  If the deployer service
is not present at all (it was undeployed) then you need to either
re-install Geronimo or get a deployment plan for the runtime
deployer and distribute it while the server is not running and then
start the server with a command like the above.  For help on this,
write to [email protected] and include the contents of your
config-store/index.properties and var/config/config.xml files.

If you get errors indicating that a module was not recognized, it may mean that you are missing the J2EE deployment descriptor for the module. For example, deploying a WAR with no WEB-INF/web.xml deployment descriptor results in an error like this:

Error: Unable to distribute no-web-xml.war: Cannot deploy the
requested application module
(moduleFile=/tmp/geronimo-deployer44623.tmpdir/no-web-xml.war)

To fix that, you'll need to write and include a J2EE deployment descriptor for each module. However, since this is the second condition that causes the same error message, there are a couple things to look into if it comes up.

In the case of resource references configured in your J2EE deployment descriptor but not resolved in your Geronimo deployment plan, the server makes its best attempt to match based on the resource name. If that doesn't work, you'll get an error like this:

Error: Unable to distribute no-plan.war: Unknown or ambiguous
connection factory name query:
geronimo.server:J2EEServer=geronimo,J2EEApplication=null,
j2eeType=JCAManagedConnectionFactory,
name=jms/TestConnectionFactory,*
match count: 0

To fix this, you'll need to add a naming:resource-ref block to your Geronimo deployment plan that specifically identifies the resource that the deployment descriptor reference should resolve to.

Another potential problem occurs with web applications when the web.xml deployment descriptor contains security settings (such as <security-role> or <security-constraint>) but the web application is not deployed with a Geronimo deployment plan or is deployed with a plan that does not contain security settings. In other words, the web.xml indicates that security and/or login should apply to the web application, but it is not hooked up to a security realm and specific users or groups with a Geronimo deployment plan.

Error: Unable to distribute test.ear: web.xml includes security
elements but Geronimo deployment plan is not provided or does not
contain <security-realm-name> element necessary to configure
security accordingly.

To fix this, add a geronimo-web.xml deployment plan with <security-realm-name> and <security> elements (though the <security> element may instead appear in the deployment plan for an EAR, if the web application is in an EAR). For more information, see Chapter 9, Security Configuration [DRAFT (1.0-pre)] and Chapter 11, Web Applications (WARs) [DRAFT (1.0)].

A similar error that comes up is:

Error: Unable to distribute test.ear: You have specified a
<security-realm-name> for the webapp
geronimo.server:J2EEApplication=TestEAR,J2EEServer=geronimo,
j2eeType=WebModule,name=test-web.war
but no <security> configuration (role mapping) is supplied in the
Geronimo plan for the web application (or the Geronimo plan for the
EAR if the web app is in an EAR)

This is essentially the same issue as above, except that the <security-realm-name> was specified, but there is no <security> element in either geronimo-web.xml or geronimo-application.xml.