ci.maven

The Liberty Maven plugin supports install and operational control of Liberty runtime and servers. Use it to manage your application on Liberty for integration test and to create Liberty server packages.

• Build
• Plugins
  • Liberty Maven Plugin
    • Java support
    • Release 3.0 differences
    • Configuration
    • Goals
• Packaging types
  • liberty-assembly
• Getting started

Usage - TLDR

• mvn liberty:dev : All-in-one goal: installs Liberty, features, starts server and deploys app. Runs in the background while you develop your application. Applies code and configuration changes (and optionally runs tests) for immediate feedback
• mvn liberty:help : List Liberty plugin goals
• mvn liberty:help -Ddetail=true -Dgoal=dev : Detailed information on parameters for goal, e.g. 'dev'

Build

Use Maven 3.5.0 or later to build the Liberty Maven plugin. We conveniently provide the maven-wrapper script, so you do not need to download maven yourself if you are not using it yet.

• ./mvnw install : builds the plugin, skipping all tests
• ./mvnw install -Poffline-its -DlibertyInstallDir=<liberty_install_directory> : builds the plugin and runs the integration tests by providing an existing installation.
• ./mvnw install -Ponline-its -Druntime=<ol|wlp> -DruntimeVersion=<runtime_version> : builds the plugin and runs the integration tests by downloading a new server. Set runtime to ol to run tests using the Open Liberty runtime, or wlp to run tests using the WebSphere Liberty Java EE 7 runtime.

Plugins

Liberty Maven Plugin

The Liberty Maven Plugin provides a number of goals for managing a Liberty server and applications. Maven 3.5.0 or later is recommended to use the Liberty Maven Plugin.

Java Support

The Liberty Maven Plugin is tested with Long-Term-Support (LTS) releases of Java. The plugin, as of release 3.7, supports Java 8, 11 and 17. Prior to this version, the plugin is supported on Java 8 and 11.

Release 3.0 differences

The new capabilities and behavior differences are summarized in the Liberty Maven Plug-in 3.0 release notes.

Configuration

To enable Liberty Maven Plugin in your project add the following to your pom.xml:

<project>
    ...
    <build>
        <plugins>
            <!-- Enable liberty-maven-plugin -->
            <plugin>
                <groupId>io.openliberty.tools</groupId>
                <artifactId>liberty-maven-plugin</artifactId>
                <version>3.8.1</version>
                <!-- Specify configuration, executions for liberty-maven-plugin -->
                ...
            </plugin>
        </plugins>
    </build>
    ...
</project>

If you are using a snapshot version of Liberty Maven Plugin then you will also need to add the following plugin repository to your pom.xml:

<project>
    ...
    <pluginRepositories>
        <!-- Configure Sonatype OSS Maven snapshots repository -->
        <pluginRepository>
            <id>sonatype-nexus-snapshots</id>
            <name>Sonatype Nexus Snapshots</name>
            <url>https://oss.sonatype.org/content/repositories/snapshots/</url>
            <snapshots>
                <enabled>true</enabled>
            </snapshots>
            <releases>
                <enabled>false</enabled>
            </releases>
        </pluginRepository>
    </pluginRepositories>
    ...
</project>

Liberty installation configuration

The Liberty Maven Plugin must first be configured with the Liberty server installation information. The installation information can be specified as:

• A Maven artifact
• An existing installation directory
• A packaged server

Installing from a Maven artifact is the default installation method. The default runtime artifact is the latest version of io.openliberty:openliberty-kernel. In order to configure WebSphere Liberty for installation, specify the runtimeArtifact with the com.ibm.websphere.appserver.runtime groupId and the specific artifactId and version that is needed. For a full list of artifacts available, see the Liberty installation configuration documentation.

Example using the runtimeArtifact parameter to install a WebSphere Liberty runtime from a Maven artifact:

<plugin>
    <groupId>io.openliberty.tools</groupId>
    <artifactId>liberty-maven-plugin</artifactId>
    <version>3.8.1</version>
    <configuration>
        <runtimeArtifact>
            <groupId>com.ibm.websphere.appserver.runtime</groupId>
            <artifactId>wlp-webProfile8</artifactId>
            <version>23.0.0.2</version>
            <type>zip</type>
        </runtimeArtifact>
    </configuration>
</plugin>

To install an Open Liberty beta runtime, specify the runtimeArtifact with the io.openliberty.beta groupId, open liberty-runtime artifactId and the version that is needed.

Example using the runtimeArtifact parameter to install an Open Liberty beta runtime from a Maven artifact:

<plugin>
    <groupId>io.openliberty.tools</groupId>
    <artifactId>liberty-maven-plugin</artifactId>
    <version>3.8.1</version>
    <configuration>
        <runtimeArtifact>
            <groupId>io.openliberty.beta</groupId>
            <artifactId>openliberty-runtime</artifactId>
            <version>23.0.0.3-beta</version>
            <type>zip</type>
        </runtimeArtifact>
    </configuration>
</plugin>

The Liberty Maven Plugin can also download and install a Liberty server from the Liberty repository or other location using the install parameter.

Goals

The Liberty Maven Plugin provides the following goals.

Goal	Description
clean	Deletes every file in the ${outputDirectory}/logs, ${outputDirectory}/workarea, ${userDirectory}/dropins or ${userDirectory}/apps.
compile-jsp	Compile JSPs in the src/main/webapp into the target/classes directory
create	Create a Liberty server.
debug	Start a Liberty server in debug mode.
deploy	Copy applications to the Liberty server's dropins or apps directory. If the server instance is running, it will also verify the applications started successfully.
dev	Start a Liberty server in dev mode.*
devc	Start a Liberty server in dev mode in a container.*
display-url	Display the application URL in the default browser.
dump	Dump diagnostic information from the server into an archive.
generate-features	Scan the class files of an application and create a Liberty configuration file in the source configuration directory that contains the Liberty features the application requires.*
install-feature	Install a feature packaged as a Subsystem Archive (esa) to the Liberty runtime.
install-server	Installs the Liberty runtime. This goal is implicitly invoked by all the other plugin goals and usually does not need to be executed explicitly.
java-dump	Dump diagnostic information from the server JVM.
package	Package a Liberty server.
prepare-feature	Prepare a user feature for installation to the Liberty runtime.
run	Start a Liberty server in the foreground. The run goal implicitly creates the server, installs features referenced by the server.xml file, and deploys the application before starting the Liberty server.
start	Start a Liberty server in the background. The server instance will be automatically created if it does not exist.
status	Check a Liberty server status.
stop	Stop a Liberty server. The server instance must exist and must be running.
test-start	Allows you to bypass automatically starting the server during the pre-integration-test phase with pom configuration or a Liberty-specific command line argument.
test-stop	Allows you to bypass automatically stopping the server during the post-integration-test phase with pom configuration or a Liberty-specific command line argument.
undeploy	Undeploy an application to a Liberty server. The server instance must exist and must be running.
uninstall-feature	Uninstall a feature from the Liberty runtime.

*The dev, devc, and generate-features goals have a runtime dependency on IBM WebSphere Application Server Migration Toolkit for Application Binaries, which is separately licensed under IBM License Agreement for Non-Warranted Programs. For more information, see the license. Note: The dev and devc goals have this dependency only when auto-generation of features is turned on. By default, auto-generation of features is turned off.

Common Parameters

Parameters shared by all goals. See common parameters.

Common Server Parameters

Additional parameters shared by all server-based goals. See common server parameters.

Extensions

Extensions improve the compatibility or user experience of third party libraries used with Liberty. The Liberty Maven Plugin provides the following extensions.

Extension	Description
configure-arquillian goal	Integrates arquillian.xml configuration for the Liberty Managed and Remote Arquillian containers in the Liberty Maven Plugin. Automatically configures required arquillian.xml parameters for the Liberty Managed container.
Spring Boot Support	The Liberty Maven Plugin provides support for Spring Boot applications, allowing you to install Spring Boot executable JARs directly to the Liberty runtime.

Packaging types

liberty-assembly

The liberty-assembly Maven packaging type is used to create a packaged Liberty server Maven artifact out of existing server installation, compressed archive, or another server Maven artifact. Any applications specified as Maven compile dependencies will be automatically packaged with the assembled server. Liberty features can also be installed and packaged with the assembled server. Any application or test code included in the project is automatically compiled and tests run at appropriate unit or integration test phase. Application code is installed as a loose application WAR file if deployPackages is set to all or project and looseApplication is set to true.

The liberty-assembly default lifecycle includes:

Phase	Goal
pre-clean	liberty:stop
process-resources	maven-resources-plugin:resources
compile	maven-compiler-plugin:compile
process-test-resources	maven-resources-plugin:testResources
test-compile	maven-compiler-plugin:testCompile
test	maven-surefire-plugin:test
prepare-package	liberty:create, liberty:prepare-feature, liberty:install-feature
package	liberty:deploy, liberty:package
pre-integration-test	liberty:test-start
integration-test	maven-failsafe-plugin:integration-test
post-integration-test	liberty:test-stop
verify	maven-failsafe-plugin:verify
install	maven-install-plugin:install
deploy	maven-deploy-plugin:deploy

Example:

<project>
    ...
    <groupId>myGroup</groupId>
    <artifactId>myServer</artifactId>
    <!-- Create Liberty server assembly -->
    <packaging>liberty-assembly</packaging>
    ...
    <dependencies>
        <!-- Package SimpleServlet.war with server assembly -->
        <dependency>
            <groupId>wasdev</groupId>
            <artifactId>SimpleServlet</artifactId>
            <version>1.0</version>
            <type>war</type>
        </dependency>
    </dependencies>
    ...
    <build>
        <plugins>
            <!-- Enable liberty-maven-plugin -->
            <plugin>
                <groupId>io.openliberty.tools</groupId>
                <artifactId>liberty-maven-plugin</artifactId>
                <version>[3.8.1,)</version>
                <extensions>true</extensions>
                <configuration>
                    <installDirectory>/opt/ibm/wlp</installDirectory>
                    <serverName>test</serverName>
                    <features>
                        <acceptLicense>true</acceptLicense>
                        <feature>mongodb-2.0</feature>
                    </features>
                    <looseApplication>true</looseApplication>
                    <deployPackages>all</deployPackages>
                </configuration>
            </plugin>
        </plugins>
    </build>
    ...
</project>

Getting started

There are multiple starters available to generate a package to start developing your first application on Open Liberty.

• Open Liberty starter
• Eclipse Starter for Jakarta EE - choose Open Liberty for the Runtime
• MicroProfile Starter - choose Open Liberty for the MicroProfile Runtime

If you want to use one of the previously published archetypes that we are no longer enhancing, refer to this documentation.