WildFly Maven Plugin to produce fully configured WildFly server

In  maven user-experience

Overview

Introduce new Maven tooling to provision a WildFly installation, configure the server and deploy application into it. The Maven tooling configuration points are similar to what WildFly Bootable JAR Maven plugin offers.

Issue Metadata

Issue

Dev Contacts

QE Contacts

Testing By

  • Engineering

  • [X] QE

Affected Projects or Components

Relevant Installation Types

  • Traditional standalone server (unzipped or provisioned by Galleon)

  • Managed domain

  • OpenShift s2i

  • Maven-controlled standalone server

  • Bootable jar

Context

Although this feature is not limited to the cloud context, the cloud execution context is the main driver for this feature.

Today, in order to execute WildFly in an Openshift context, we are relying on WildFly S2I (Source-to-Image) builder and runtime images to build and execute an WildFly application image. There is a strong coupling inside this image between the server version and the docker image that implies releasing a new image for each new WildFly release. This approach is not flexible. We should be able to build an application image for any WildFly release (even for a locally built SNAPSHOT) without having to wait for the WildFly builder image to be built/deployed.

In addition, the WildFly server located inside the builder image, enforces a set of configuration API (a set of environment variables) and bash launch scripts. At startup time, a complex CLI script generation that impacts the server startup time is mandatorily executed. Having this level of configurability should be a user choice and not be enforced by the WildFly s2i image.

To solve these pain points, we are removing in WFLY-14936 the server installation and its configuration aspects from the image.

The WildFly S2I image becomes a generic image allowing the installation and execution of any provisioned WildFly server.

Due to this removal, we need a way for customers to provision the WildFly server to be installed inside the new image when building their application. This WildFly server will run the built application inside the image.

To do so we are defining Maven tooling that handles the Galleon provisioning of the server, the application deployment and the configuration aspects.

Requirements

The existing WildFly Maven plugin has been designed to interact (mainly) with a running server instance. We are here proposing to evolve the capabilities of this plugin for one to be able to build a fully configured server containing application deployment.

This proposal adds a new kind of installation that is operated and controlled by the pom.xml file. The pom.xml file contains all the information needed to control the server and application content and versioning.

Requirements for cloud integration

  • The new package goal that this proposal adds to the Maven plugin is the goal to use during s2i build. Other goals (e.g.: provisioning, execute-commands, …​) are not expected to be used.

  • The plugin can be used in a "cloud build" context. In particular, the plugin must be usable with:

    • WildFly s2i V2 builder image for s2i in binary and source (see: WFLY-14934)

    • JKube s2i and docker binary builds (see WFLY-14938)

  • The generated server can be installed and run successfully inside a WildFly runtime image v2 defined in WFLY-14936.

The integration of this plugin for cloud integration will affect other projects. NB: The changes in these projects (to benefit from the evolution of the WildFly Maven plugin) are not part of this current proposal. These projects are:

Eventually, other technologie such as BuildPacks will be able to leverage this plugin to build cloud images for WildFly.

Hard Requirements

Plugin requirements

  • The Maven plugin produces inside the project target dir a directory (named server by default) that contains the server and any deployment.

WildFly Maven Plugin new goals

  • wildfly:package: Galleon provisioning of a server, CLI script execution, copy content to the server, deploy application (if present).

  • wildfly:provision: Galleon provisioning of a server.

In addition to these 2 new goals, we are replacing the existing automatic download and unzip of wildfly-dist by a Galleon provisioning of WildFly. This change impacts run and `start`goals).

These configuration items are common to the provision and package goals. They are used to configure Galleon to provision a server.

  • feature-packs: A list of feature-pack to install. This can be configured with the system property wildfly.provisioning.feature-packs containing a comma separated list of feature-pack locations in the form of Maven coordinates GroupId:ArtifactId:Version or producer reference.

  • log-provisioning-time: Whether to log provisioning time at the end.

  • offline-provisioning: Whether to use offline mode when the plugin resolves an artifact.

  • galleon-options: Arbitrary Galleon options used when provisioning the server.

  • provisioning-dir: The path to the directory where to provision the server. Can be an absolute path or a path relative to the Maven project build directory. When absolute and outside the project build directory, the provisioned server will be not deleted when clean occurs. It defaults to server and will result in the server being provisioned in ${project.build.directory}/server (which is resolved to target/server by default)

  • provisioning-file: The path to the provisioning.xml file to use, by default <project base dir>/galleon/provisioning.xml is used. If some feature-packs have been set, the provisioning file is being ignored.

  • record-provisioning-state: Whether to record provisioned state in .galleon directory. When false, the file .wildfly-maven-plugin-provisioning.xml is generated in the server home directory. It contains Galleon provisioning information used to provision this server.

  • layers: A set of layers to include when building-up a custom configuration. This can be configured with the system property wildfly.provisioning.layers containing a comma separated list of layers.

  • excluded-layers: A set of layers to exclude when building-up a custom configuration. This can be configured with the system property wildfly.provisioning.layers.excluded containing a comma separated list of layers.

  • layers-configuration-file-name: The name of the configuration file generated from layers. Default value is standalone.xml. If no layers have been configured, setting this parameter is invalid.

  • overwrite-provisioned-server: By default if the server referenced from the provisioning-dir exists when provision/package goals are called, the provisioning/packaging is disabled. By setting this parameter to true, the provisioned server will get deleted and provisioning/packaging will occur.

provision goal specific behavior

Calling provision goal without any Galleon configuration items (no feature-pack provided nor provisioning.xml file) will provision the same default server that we are provisioning when calling run and start goals.

package goal specific configuration items and behavior

A Galleon configuration is expected, if no galleon configuration is found, the goal execution fails.

The configuration items names, when applicable, are re-using the names that are in use in existing WildFly Maven plugin goals.

  • packaging-scripts: A list of execution of CLI scripts and commands. Each execution can contain: a list of CLI scripts, a list of commands, a list of properties files, a list of java options, the ability to resolve or not expressions located in CLI scripts locally (false by default) and system properties for the CLI forked process. NB: CLI commands are automatically executed in the context of an embedded server.

  • extra-server-content-dirs: A list of directories to copy content to the provisioned server inside a forked process. The content is copied into the provisioned server keeping the directory structure found inside the extra directories. e.g.: my-extra-dir/standalone/configuration/foo.properties, the file foo.properties will be located inside the <provisioned server>/standalone/configuration/foo.properties.

  • filename: The name of the artifact to deploy. A look-up is done inside the project build directory. By default a lookup is done to retrieve the primary artifact to deploy. If no file is found, no deployment is operated.

  • name: The name of the deployment. By default the file name is used.

  • runtime-name: The runtime name of the deployment. By default the file name is used. NB: In order to deploy the deployment inside the root context, ROOT.war runtime name is to be used.

  • server-config: The server config to use when executing CLI scripts and deploying artifact. Is standalone.xml by default. If layers-configuration-file-name has been set, this property is ignored and the deployment is deployed inside the configuration referenced from layers-configuration-file-name.

  • stdout: Indicates how stdout and stderr should be handled for the forked CLI process. By default the output is redirected to the current process. none to disable output, System.out or System.err to redirect to the current process. Any other value is assumed to be the path to a file and the out/err will be written there. All CLI executions output is appended to the file.

run and start goals impact

  • If jboss-home has not been set and no server if found in <buildDir>/<provisioning-dir> a server is provisioned.

  • The artifact, groupId, artifactId, classifier, packaging configuration items have been removed.

  • The version configuration item is kept allowing to identify a WildFly version to install.

  • The provisioning-dir allows to specify where to (find/provision) the server.

execute-commands goal impact

  • The ability to provision a server if no server installation is found is removed.

Incremental development workflow on bare-metal

A user should be able to provision/package and start the server then incrementally make change to his application and do some manual testing (eg: using a web browser to interact with the application).

Typical sequence of steps for an application in which the pom.xml contains a configured wildfly:package goal:

  • mvn package: deployment deployed to trimmed WildFly server in path referenced by provisioning-dir.

  • mvn wildfly:start: server started

  • Developper makes change

  • mvn wildfly:deploy: deployment re-deployed

  • mvn wildfly:shutdown: server shutdown

Typical sequence of steps for an application in which the pom.xml doesn’t contain a configured wildfly:package goal:

  • mvn package wildfly:package: deployment deployed + provision default WildFly server in path referenced by provisioning-dir. In order to trim the server, one can provide: -Dwildfly.provisioning.layers=cloud-server -Dwildfly.provisioning.feature-packs=org.wildfly:wildfly-galleon-pack:26.0.1.Final

  • mvn wildfly:start: server started

  • Developper makes change

  • mvn wildfly:deploy: deployment deployed

  • mvn wildfly:shutdown: server shutdown

WildFly Maven plugin versioning

A new major version would contain these new features.

Impact on quickstarts

  • A set of quickstarts should be refactored to use this plugin on the cloud. This should be covered by another proposal.

Nice-to-Have Requirements

  • NONE

Non-Requirements

  • No support for domain mode when packaging an application.

Test Plan

  • Add new Maven plugin tests in plugin source repository:

    • Add a test that packages an application based on a set of layers + CLI script + extra content. Check that the provisioned server is valid.

    • Add a test that provisions a server based on a set of layers. Check that the provisioned server is valid.

  • Add new integration tests in wildfly-s2i V2 image repository.

Community Documentation

Release Note Content

The WildFly Maven plugin org.wildfly.plugins:wildfly-maven-plugin has been evolved to support Galleon provisioning. A new package Maven plugin goal allows you to build a fully configured server containing your application. In addition, some deprecated features have been removed:

  • The ability to provision a server if no server installation is found has been removed from the execute-commands goal.

  • The artifact, groupId, artifactId, classifier, packaging configuration items have been removed from the run and start goals.