<commit_before>:toc:
:toc-placement!:

= Provisioning Manager Tool

ifdef::env-github[]
[link=https://travis-ci.org/aloubyansky/pm]
image:https://travis-ci.org/aloubyansky/pm.svg?branch=master["Build Status", link="https://travis-ci.org/aloubyansky/pm"]
endif::[]

toc::[]

= Project Modules

== Module `pm-parent`

Defines main version and common dependencies of the project.

== Module `feature-pack-api`

General provisioning and feature-pack API.

== Module `wildfly-feature-pack-api`

WildFly-specific provisioning and feature-pack API is basically a façade
over the general provisioning and feature-pack API which makes
it easier to build WildFly-specific provisioning config.

== Module `feature-pack-build-maven-plugin`

Maven Mojo implementations (i.e. goals in Maven plugins).

== Module `wildfly-feature-pack-maven-plugin`

WildFly-specific Maven Mojo implementation that builds WildFly feature-packs.
The plugin has to be included into the WildFly feature-pack build modules as

[source,xml]
----
<plugin>
    <groupId>org.jboss.pm</groupId>
    <artifactId>wildfly-feature-pack-maven-plugin</artifactId>
    <executions>
        <execution>
            <id>feature-pack-build</id>
            <goals>
                <goal>wf-build</goal>
            </goals>
            <phase>compile</phase>
        </execution>
    </executions>
</plugin>
----

== Module `tool`

Command line interface which allows to:
  
* Build feature-packs and install them into the Maven repository;
* Provision an installation by pulling the feature-packs from the
  Maven repository and installing them at the specified location.

The Maven assembly plug-in is configured to create a single executable JAR
file which contains all the dependencies.

= CLI Commands

== Command `feature-pack --action install`

Builds a feature pack for the specified WildFly-based installation and
installs the feature pack into the Maven repository.
  
Arguments:

[source,shell]
----
--install-dir - filesystem path to the WildFly-based installation for which 
                the feature pack should be built.

--workdir     - optional, useful for debugging, specifies the work directory
                used by the tool to layout feature packs before ZIPing
                and installing into the maven repository. The directory is
                not automatically removed when the tool has finished
                the task.
                If the argument is not specified, a random temporary
                directory will be created instead and removed after the tool
                has finished the task.
----

== Command `pm`

Provisions an installation at the specified location by reading its
specification from the specified provisioning XML file.

Arguments:
  
[source,shell]
----
--provisioning-xml - filesystem path to the provisioning XML file which
                     defines an installation in terms of the feature-packs

--install-dir      - root directory for the installation to be provisioned
----

Assuming the feature-packs are built and installed into the Maven repository,
these are the commands I use to test provisioning WildFly builds:

[source,shell]
----
[pm] pm --install-dir install/wf-full --provisioning-xml tool/src/test/resources/wf-full-provisioning.xml
[pm] pm --install-dir install/wf-web --provisioning-xml tool/src/test/resources/wf-web-provisioning.xml
[pm] pm --install-dir install/wf-core --provisioning-xml tool/src/test/resources/wf-core-provisioning.xml
----

= Building and launching the tool
 
The tool can be built by executing the following Maven command:

[source,shell]
----
mvn clean install
----

The executable JAR will be built in `pm/tool/target/pm-tool.jar`

There is also a convenience `do.sh` script in the root directory
of the project. If executed w/o arguments, it'll build and launch the tool.

`./do.sh package` will only build the tool.
`./do.sh run` will only launch the already built tool.

= Building WildFly feature-packs

To be able to build WildFly (core, servlet and full) feature-packs the WildFly Maven plugins
from this project have to be included into the target WildFly Maven build configuration.

The following branches can be used as examples:

* WildFly Core: https://github.com/aloubyansky/wildfly-core/tree/new-feature-pack
* WildFly Servlet and Full: https://github.com/aloubyansky/wildfly/tree/new-feature-pack<commit_msg>description of wildfly-feature-pack-build.xml and wildfly-tasks.xml files<commit_after>:toc:
:toc-placement!:

= Provisioning Manager Tool

ifdef::env-github[]
[link=https://travis-ci.org/aloubyansky/pm]
image:https://travis-ci.org/aloubyansky/pm.svg?branch=master["Build Status", link="https://travis-ci.org/aloubyansky/pm"]
endif::[]

toc::[]

= Project Modules

== Module `pm-parent`

Defines main version and common dependencies of the project.

== Module `feature-pack-api`

General provisioning and feature-pack API.

== Module `wildfly-feature-pack-api`

WildFly-specific provisioning and feature-pack API is basically a façade
over the general provisioning and feature-pack API which makes
it easier to build WildFly-specific provisioning config.

== Module `feature-pack-build-maven-plugin`

Maven Mojo implementations (i.e. goals in Maven plugins).

== Module `wildfly-feature-pack-maven-plugin`

WildFly-specific Maven Mojo implementation that builds WildFly feature-packs.
The plugin has to be included into the WildFly feature-pack build modules as

[source,xml]
----
<plugin>
    <groupId>org.jboss.pm</groupId>
    <artifactId>wildfly-feature-pack-maven-plugin</artifactId>
    <executions>
        <execution>
            <id>feature-pack-build</id>
            <goals>
                <goal>wf-build</goal>
            </goals>
            <phase>compile</phase>
        </execution>
    </executions>
</plugin>
----

== Module `tool`

Command line interface which allows to:
  
* Build feature-packs and install them into the Maven repository;
* Provision an installation by pulling the feature-packs from the
  Maven repository and installing them at the specified location.

The Maven assembly plug-in is configured to create a single executable JAR
file which contains all the dependencies.

= CLI Commands

== Command `feature-pack --action install`

Builds a feature pack for the specified WildFly-based installation and
installs the feature pack into the Maven repository.
  
Arguments:

[source,shell]
----
--install-dir - filesystem path to the WildFly-based installation for which 
                the feature pack should be built.

--workdir     - optional, useful for debugging, specifies the work directory
                used by the tool to layout feature packs before ZIPing
                and installing into the maven repository. The directory is
                not automatically removed when the tool has finished
                the task.
                If the argument is not specified, a random temporary
                directory will be created instead and removed after the tool
                has finished the task.
----

== Command `pm`

Provisions an installation at the specified location by reading its
specification from the specified provisioning XML file.

Arguments:
  
[source,shell]
----
--provisioning-xml - filesystem path to the provisioning XML file which
                     defines an installation in terms of the feature-packs

--install-dir      - root directory for the installation to be provisioned
----

Assuming the feature-packs are built and installed into the Maven repository,
these are the commands I use to test provisioning WildFly builds:

[source,shell]
----
[pm] pm --install-dir install/wf-full --provisioning-xml tool/src/test/resources/wf-full-provisioning.xml
[pm] pm --install-dir install/wf-web --provisioning-xml tool/src/test/resources/wf-web-provisioning.xml
[pm] pm --install-dir install/wf-core --provisioning-xml tool/src/test/resources/wf-core-provisioning.xml
----

= Building and launching the tool
 
The tool can be built by executing the following Maven command:

[source,shell]
----
mvn clean install
----

The executable JAR will be built in `pm/tool/target/pm-tool.jar`

There is also a convenience `do.sh` script in the root directory
of the project. If executed w/o arguments, it'll build and launch the tool.

`./do.sh package` will only build the tool.
`./do.sh run` will only launch the already built tool.

= Building WildFly feature-packs

To be able to build WildFly (core, servlet and full) feature-packs the WildFly Maven plugins
from this project have to be included into the target WildFly Maven build configuration.

The following branches can be used as examples:

* WildFly Core: https://github.com/aloubyansky/wildfly-core/tree/new-feature-pack
* WildFly Servlet and Full: https://github.com/aloubyansky/wildfly/tree/new-feature-pack

== WildFly feature-pack build configuration

WildFly feature-pack building Maven plugin expects an XML file named wildfly-feature-pack-build.xml
which contains information about the feature-pack dependencies on other feature-packs, what additional
content to include into the feature-pack, configuration assembly instructions and post provisioning tasks.

== WildFly post provisioning/install tasks configuration

When the target installation has been provisioned content-wise, there still tasks remain to perform to make
the just provisioned installation usable. One of the essential ones is to assemble/adjust the configuration
to what the user has selected. Other tasks include setting file permissions, correcting line endings for
certain files, create expected directories.

These tasks are described in wildfly-tasks.xml file which is included into the resources of the WildFly feature-pack.
The file is created by the WildFly feature-pack building Maven plugin based on the wildfly-feature-pack-build.xml.
{'fraction_non_alphanumeric': 0.08331641972802922, 'fraction_numerical': 0.0, 'mean_word_length': 3.42722371967655, 'pattern_counts': {'":': 0, '<': 39, '<?xml version=': 0, '>': 39, 'https://': 10, 'lorem ipsum': 0, 'www.': 0, 'xml': 21}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1586400', 'n_tokens_mistral': 2785, 'n_tokens_neox': 2632, 'n_words': 1063}