| 10.4. The Deploy Tool | ||
|---|---|---|
 | Chapter 10. Development & Deployment Overview [DRAFT (1.0)] |  |
| 10.4. The Deploy Tool | ||
|---|---|---|
| | Chapter 10. Development & Deployment Overview [DRAFT (1.0)] | |
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.
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).
The deploy tool terminology revolves around the J2EE Application Deployment specification (JSR-88). The specific terms as they apply to Geronimo are:
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.
The configId that uniquely identifies a deployed module (aka a server configuration). This is set in the Geronimo deployment descriptor for the module.
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”.
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.
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.
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.
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.
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).
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.
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.
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.
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".)
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".)
Log all exceptions to System.err.
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.
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.
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.
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:
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.
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.
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.
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.
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.
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:
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.
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.
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]](images/tip.png) | 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). | |
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.
| |  | |
| 10.3. Geronimo Deployment Plans |  | 10.5. Maven 1.x Deployment Plugin |