Deployment

Deployment From Maven

The preferred deployment method for a project built with maven is to use the geronimo maven deployment plugin to install an application specific copy of geronimo and deploy one or more modules to it. More extensive instructions are on the Running page. Generally, a geronimo deployment plan is advisable. A simple default plan can be generated for all module types except resource adapters. The plan can either be included in the module next to the spec-required deployment descriptor or external to the module and located by an additional parameter to the deploy command. Again, this is discussed in more detail on the Running page. Additional aspects of each deployment plan are discussed below.

Deployment From the Command Line

The Geronimo deployment tool is packaged in the executable jar bin/deployer.jar. The deployer uses a XML deployment plan to figure out what to do and this xml file determined by the module type. Ultimately this will be produced by a JSR-88 tool but for now an XML aware text editor is the best choice. To get the basics on the deployer, run: java -jar bin/deployer.jar For help on connectivity options: java -jar bin/deployer.jar help options For help on a command: java -jar bin/deployer.jar help command For help on all commands: java -jar bin/deployer.jar help all Some typical commands: Server Running
```
java -jar bin/deployer.jar --user system --password manager deploy my-web-app.war
java -jar bin/deployer.jar --user system --password manager deploy my-web-app.war geronimo-web.xml
java -jar bin/deployer.jar --user system --password manager redeploy my-web-app.war MyWebConfigID
java -jar bin/deployer.jar --user system --password manager list-modules --started
java -jar bin/deployer.jar --user system --password manager list-modules --stopped
java -jar bin/deployer.jar --user system --password manager stop MyWebConfigID
java -jar bin/deployer.jar --user system --password manager start MyWebConfigID
java -jar bin/deployer.jar --user system --password manager deploy my-service-plan.xml
```
Server Not Running
```
java -jar bin/deployer.jar distribute my-web-app.war
java -jar bin/deployer.jar distribute my-web-app.war geronimo-web.xml
java -jar bin/deployer.jar distribute my-service-plan.xml
```
NOTE: Deployer will try to connect to a running Geronimo instance before starting up its own itself. It's important when you encounter any weird error messages during deployment and will be tearing your hair out over what might be wrong. It can be that the deployer has connected to a defunct server or a server without Deployer running. NOTE: Though you can deploy while the server is running, that still only works if you're on the same machine as the server. Deployment to remote machines will come. Login: The username and password used to deploy to a running server are set in var/security/users.properties, and the user should be a member of the admin group in var/security/groups.properties. If you don't specify a username and password on the command line, you will be prompted if they turn out to be necessary.

Deployment from Ant

Here's an example fragment from an Ant build.xml file:

  <target name="deploy" description="Deploy the application into Geronimo">
    <java jar="path/to/deployer.jar" fork="true">
      <arg line="--user system --password manager deploy YourApplication.ear" />
    </java>
  </target>

General Configuration

The schema of Geronimo plans is located in the schema/geronimo-config.xsd file (in the repo it's in modules/deployment/src/schema/geronimo-config.xsd). The very minimal and working plan looks as follows:
- ```
<?xml version="1.0" encoding="UTF-8"?>
<configuration
    xmlns="http://geronimo.apache.org/xml/ns/deployment"
    configId="enter/a/descriptive/name/here"
    >

    <gbean name="geronimo.test:name=MyMockGMBean" 
           class="org.apache.geronimo.deployment.Deployer" />

</configuration>
```
  All of the configuration files shown below support the following common element:
- ```
<dependency>
    <uri>junit/jars/junit-3.8.jar</uri>
</dependency>

<dependency>
    <groupId>junit</groupId>
    <artifactId>junit</artifactId>
    <version>3.8</version>
</dependency>
```
  These two equivalent declarations, add a dependency on junit-3.8.jar. When Geronimo starts this configuration it will search its own repository (not the maven repository) for the specified file and will add it to the class path of the configuration.

J2EE Application (.ear file)

Configuration

If you're using the M2 snapshot or an older version you must add a geronimo-application.xml file to your .ear file. If you're using recent (post September 2004) CVS versions of Geronimo then this is optional. Here's an example:
- ```
<?xml version="1.0" ?>
<application xmlns="http://geronimo.apache.org/xml/ns/j2ee/application"
  configId="YourApplication"
  parentId="org/apache/geronimo/Server" />
```

Deployment

To deploy and start your application, execute the following command from the Geronimo home directory:
- ```
java -jar bin/deployer.jar deploy YourApplication.ear
```

Web Application

Configuration

Note: The content in this section applies to build 208887 or higher (Milestone 3 used a slightly different configuration format). When you deploy a web application in Geronimo, you can use a WEB-INF/geronimo-web.xml file to provide additional configuration settings for the web application. This may or may not be necessary, depending on what's in your WAR. An example geronimo-web.xml file follows:
- ```
<?xml version="1.0" encoding="UTF-8"?>
<web-app
    xmlns="http://geronimo.apache.org/xml/ns/web"
    configId="your/domain/name/Example"
    parentId="org/apache/geronimo/Server"
    >
    <context-root>/debug-tool</context-root>
    <context-priority-classloader>false</context-priority-classloader>
</web-app>
```
  Change the configId attribute to the configuration identifier you would like to use for your application. The configId should begin with the domain name of your organization. For example, we use org/apache/geronimo, and the OpenEJB project uses org/openejb. The remaining elements are described below:
- context-root Your application will be mounted at http://localhost:8080/<context-root>
- context-priority-classloader If true, Geronimo will load classes from the web application before the Geronimo server environment. If false, Geronimo will use normal Java class loading rules and check the Geronimo server before loading class from the web application. False is the preferred setting

Deployment

To deploy and start your web application (on a running Geronimo server) execute the following command from the Geronimo home directory:
- ```
java -jar bin/deployer.jar deploy YourWebApplication.war
```
  Also, to undeploy the webapp (note we use the name of the context here, not the path to the war file) :
- ```
java -jar bin/deployer.jar undeploy YourWebApplication
```

EJB Application

Configuration

To deploy an EJB application in Geronimo, you must add a META-INF/openejb-jar.xml file to your ejb-jar file (this restriction will be removed in a future release). An example openejb-jar.xml file follows:

<?xml version="1.0"?>

<openejb-jar
    xmlns="http://www.openejb.org/xml/ns/openejb-jar"
    configId="your/domain/name/Example"
    parentId="org/apache/geronimo/Server">

    <enterprise-beans>
        <session>
            <ejb-name>SimpleStatelessSession</ejb-name>
            <jndi-name>client/test/simple/SimpleStatelessSessionHome</jndi-name>
        </session>
    </enterprise-beans>
</openejb-jar>

Change the configId attribute to the configuration identifier you would like to use for your application. The configId should follow with the domain name of your organization.

Deployment

To deploy and start your EJB application (on a running Geronimo server) execute the following command from the Geronimo home directory:
- ```
java -jar bin/deployer.jar deploy YourEJBApplication.jar
```

Resource Adapter

Configuration

To deploy a Resource adapter into Geronimo, you must add a META-INF/geronimo-ra.xml file to your rar file (this restriction will be removed in a future release). An example JCA 1.0 geronimo-ra.xml file follows:

<?xml version="1.0" encoding="UTF-8"?>
<connector xmlns="http://geronimo.apache.org/xml/ns/j2ee"
    version="1.0"
    configId="your/domain/name/Example"
    parentId="org/apache/geronimo/Server">

    <resourceadapter>
        <outbound-resourceadapter>
            <connection-definition>
                <connectionfactory-interface>javax.sql.DataSource</connectionfactory-interface>
                <connectiondefinition-instance>
                    <name>DefaultDatasource</name>
                    <config-property-setting name="DefaultUserName"></config-property-setting>
                    <config-property-setting name="DefaultPassword"></config-property-setting>
                    <config-property-setting name="JdbcDriver">org.axiondb.jdbc.AxionDriver</config-property-setting>
                    <config-property-setting name="JdbcUrl">jdbc:axiondb:DefaultDatabase</config-property-setting>
                    <connectionmanager>
                        <!--realm-bridge>TargetRealm</realm-bridge-->
                        <blockingTimeout>100</blockingTimeout>
                        <maxSize>1</maxSize>
                        <useTransactions>true</useTransactions>
                        <useLocalTransactions>true</useLocalTransactions>
                        <useTransactionCaching>true</useTransactionCaching>
                        <useConnectionRequestInfo>false</useConnectionRequestInfo>
                        <useSubject>false</useSubject>
                    </connectionmanager>
                </connectiondefinition-instance>

            </connection-definition>

        </outbound-resourceadapter>
    </resourceadapter>
</connector>

Here's an example JCA 1.5 geronimo-ra.xml. This file works with Geronimo's CVS HEAD as of 2005-01-11, but not with older code:

<?xml version="1.0" encoding="UTF-8"?>
<connector xmlns="http://geronimo.apache.org/xml/ns/j2ee" version="1.5"
    configId="testRA"
    parentId="org/apache/geronimo/Server">
    <resourceadapter>
        <resourceadapter-instance>
            <resourceadapter-name>testRA</resourceadapter-name>
            <workmanager>
                <gbean-link>DefaultWorkManager</gbean-link>
            </workmanager>
        </resourceadapter-instance>
    </resourceadapter>
</connector>

The schema for geronimo-ra.xml is in the source tree at modules/connector/src/schema/geronimo-connector_1_5.xsd. Change the configId attribute to the configuration identifier you would like to use for your application. The configId should follow with the domain name of your organization.

Deployment

To deploy and start your resource adapter (on a running Geronimo server) execute the following command from the Geronimo home directory:
- ```
java -jar bin/deployer.jar deploy YourResourceAdapter.rar 
```

Database configuration

Read about it at Database_Configuration

Services

Configuration

Geronimo can deploy generalized GBean services in addition to the standard J2EE deployment types. An example service-plan.xml file follows:

<configuration
    xmlns="http://geronimo.apache.org/xml/ns/deployment"
    configId="your/domain/name/Example"
    parentId="org/apache/geronimo/System"
    >

    <gbean name="some.domain:name1=value1,name2=value2" class="your.package.SomeGBean">
        <attribute name="SomeAttribute" type="int">42</attribute>
        <reference name="SomeReference">some.domain:type=SomeOtherGBean</reference>
    </gbean>
</configuration>

Change the configId attribute to the configuration identifier you would like to use for your application. The configId should follow with the domain name of your organization.

Deployment

To deploy and start your service (on a running Geronimo server) execute the following command from the Geronimo home directory:
- ```
java -jar bin/deployer.jar deploy YourService-plan.xml
```

Undeployment

Is it possible to undeploy a module? It doesn't appear so, since o.a.g.deployment.Deployer has a deploy() method but no undeploy().

You can "undeploy" by hacking around in the target/config-store directory. The contents appears to be a properties file called index.properties, and a set of subdirectories with numeric names. The properties key is the configuration name and the value is the numeric name of the subdirectory that contains that configuration. So to "undeploy" a configuration you just remove its entry from index.properties and delete its directory.

Low-level details

When the deployer is invoked, org.apache.geronimo.deployment.cli.DeployTool of the deploy-tool module is executed. Take a look at the class when in a urgent need to figure out how Geronimo deployment goes.