Basic Usage

Assembly Artifact Configuration

Before the plugin can start or stop a server, it needs to know about the assembly (or assemblies) which it will install.

This example shows one assembly, which will be used to install unless the assemblyArchive parameter has been set (see below section on Installing an Assembly).

NOTE: Archive files MUST be a ZIP files (or be in the same format, like a JAR).

<plugin>
    <groupId>org.apache.geronimo.plugins</groupId>
    <artifactId>geronimo-maven-plugin</artifactId>
    
    <configuration>
        <assemblies>
            <assembly>
                <groupId>org.apache.geronimo.assemblies</groupId>
                <artifactId>geronimo-jetty-j2ee</artifactId>
                <version>${pom.version}</version>
                <classifier>bin</classifier>
                <type>zip</type>
            </assembly>
        </assemblies>
    </configuration>
</plugin>

Multiple assemblies may be specified. Each must have a unique id, and either defaultAssemblyId or assemblyId must be configured to inform the plugin which assembly to use.

<plugin>
    <groupId>org.apache.geronimo.plugins</groupId>
    <artifactId>geronimo-maven-plugin</artifactId>
    
    <configuration>
        <assemblies>
            <assembly>
                <id>jetty</id>
                <groupId>org.apache.geronimo.assemblies</groupId>
                <artifactId>geronimo-jetty-j2ee</artifactId>
                <version>${pom.version}</version>
                <classifier>bin</classifier>
                <type>zip</type>
            </assembly>
            
            <assembly>
                <id>jetty-minimal</id>
                <groupId>org.apache.geronimo.assemblies</groupId>
                <artifactId>geronimo-jetty-minimal</artifactId>
                <version>${pom.version}</version>
                <classifier>bin</classifier>
                <type>zip</type>
            </assembly>
            
            <assembly>
                <id>tomcat</id>
                <groupId>org.apache.geronimo.assemblies</groupId>
                <artifactId>geronimo-tomcat-j2ee</artifactId>
                <version>${pom.version}</version>
                <classifier>bin</classifier>
                <type>zip</type>
            </assembly>
            
            <assembly>
                <id>tomcat-minimal</id>
                <groupId>org.apache.geronimo.assemblies</groupId>
                <artifactId>geronimo-tomcat-minimal</artifactId>
                <version>${pom.version}</version>
                <classifier>bin</classifier>
                <type>zip</type>
            </assembly>
        </assemblies>
        
        <defaultAssemblyId>jetty</defaultAssemblyId>
    </configuration>
</plugin>

Starting Geronimo Server

Once you have configured an assembly (or assemblies with a default), then you can simply start the server.

The assembly archive will be installed if it does not already exist, or if the plugin detects that the current archive is newer than the last installation.

mvn geronimo:start

If you have a pre-existing assembly installed and you want to use that, you can set geronimoHome this will bypass any installation logic completely.

mvn geronimo:start -DgeronimoHome=/path/to/assembly

Some additional flags may be passed in to alter the startup behavior. For example to enable verbose mode:

mvn geronimo:start -Dverbose=true

Optional JVM debug arguments may be configured.

<plugin>
    <groupId>org.apache.geronimo.plugins</groupId>
    <artifactId>geronimo-maven-plugin</artifactId>

    <configuration>
        <debugArguments>
            <argument>-Xdebug</argument>
            <argument>-Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=n</argument>
        </debugArguments>
    </configuration>
</plugin>

By setting the debug parameter the JVM will be started in debug mode.

mvn geronimo:start -Ddebug=true

Stopping Geronimo Server

To stop a server using the defaults, which is probably fine in most cases, just invoke the stop goal.

Stopping a server does not require an assembly to be installed.

mvn geronimo:stop

Additional parameters may be passed in on the command-line:

mvn geronimo:stop -Dusername=system -Dpassword=manager -Dport=1099

Selecting an Assembly

Once you have a set of assemblies configured with unique ids, you can specify the id of the assembly you wish to use on the command-line:

mvn geronimo:start -DassemblyId=tomcat

Start/Stop for Integration Testing

For inline integration testing, you can set the background parameter on the start goal to start the server, wait for it to load and then return control to Maven so that it can execute integration tests.

<plugin>
    <groupId>org.apache.geronimo.plugins</groupId>
    <artifactId>geronimo-maven-plugin</artifactId>
    <executions>
        <execution>
            <id>start-server</id>
            <phase>pre-integration-test</phase>
            <goals>
                <goal>start</goal>
            </goals>
            <configuration>
                <background>true</background>
            </configuration>
        </execution>
        
        <execution>
            <id>stop-server</id>
            <phase>post-integration-test</phase>
            <goals>
                <goal>stop</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Installing an Assembly

To just run the installation of the assembly:

mvn geronimo:install -DassemblyId=tomcat

To install a specific assembly archive, which need not be in the repository:

mvn geronimo:install -DassemblyArchive=/path/to/assembly.zip

For this to work, the file MUST be a ZIP (or be in the same format, like a JAR) and the archive should contain a full server assembly, specifically it needs to have a bin/server.jar entry. This entry is used to discover geronimoHome.

You can also change the base directory where the assembly is extracted to by setting the installDirectory parameter. This is useful for a certain operating system that has a horribly small limit on the maximum size of a path name.

NOTE: The directory structure of the archive is still preserved when it is extracted.

mvn geronimo:install -DinstallDirectory=c:\