Fabric8 Documentation

Fabric8 Maven Plugin

This maven plugin makes it easy to create or update a fabric profile from your maven project.

When you deploy your project to a fabric profile with this plugin the following takes place:

• uploads any artifacts into the fabric's maven repository
• lazily creates the fabric profile or version you specify
• adds/updates the maven project artifact into the profile configuration
• adds any additional parent profile, bundles or features to the profile.

Configuring the plugin

First you will need to edit your ~/.m2/settings.xml file to add the fabric server's user and password so that the maven plugin can login to the fabric..

e.g. add this to the <servers> element:

<server>
  <id>fabric8.upload.repo</id>
  <username>admin</username>
  <password>admin</password>
</server>

If you don't do this, the first time you use the fabric8 plugin it will ask you if you wish to update your ~/.m2/settings.xml file and prompt you for the information; then update it.

The default fabric upload maven repo ID is fabric8.upload.repo. You can define as many <server> elements in your settings file as you like for each of the fabrics you wish to work with. Then to pick the credentials to use for a server specify the server id as the serverId property on the fabric8 maven plugin configuration section (see below) or use the fabric8.serverId maven property.

Using the plugin

To use the fabric8 maven plugin to deploy into a fabric profile on any maven project just type:

mvn io.fabric8:fabric8-maven-plugin:1.2.0.Beta4:deploy

If you have added the fabric8 maven plugin to your pom.xml as follows:

<plugins>
  <plugin>
    <groupId>io.fabric8</groupId>
    <artifactId>fabric8-maven-plugin</artifactId>
  </plugin>
</plugins>

Then you can use the more concise maven goal instead:

mvn fabric8:deploy

The project will then be built and deployed into a profile in the fabric. By default the profile is named $group-$artifact but you can override the profile ID, version ID and location of the Fabric Jolokia URL via the maven plugin configuration or via the command line.

e.g. to try it out

cd quickstarts/rest
mvn io.fabric8:fabric8-maven-plugin:1.2.0.Beta4:deploy

Then you should see this profile being created at the my-rest/rest profile page which should have a bundle and some features added too (click on the Bundle and Feature tabs and you should see those).

Configuring the fabric server

By default the fabric8 maven plugin deploys to a local fabric server using the url

http://localhost:8181/jolokia

To use a remote fabric server you can either configure this in the plugin in the pom.xml file using the jolokiaUrl configuration as shown below

<plugins>
  <plugin>
      <groupId>io.fabric8</groupId>
      <artifactId>fabric8-maven-plugin</artifactId>
      <configuration>
        <jolokiaUrl>http://someServer:8181/jolokia</jolokiaUrl>
      </configuration>
  </plugin>
</plugins>

... or specify the url in the command line

mvn fabric8:deploy -Dfabric8.jolokiaUrl=http://someServer:8181/jolokia

Quick deploy without testing

Sometimes you may want to skip testing before deploying, if you have done a trivial change. This can be done by speciftying -DskipTests via the command line as shown:

mvn fabric8:deploy -DskipTests

Specifying the profile information in the plugin configuration

You can configure the maven plugin to explicitly specify the profile to create via the plugin <configuration> section in your pom.xml:

<plugins>
  <plugin>
      <groupId>io.fabric8</groupId>
      <artifactId>fabric8-maven-plugin</artifactId>
      <configuration>
        <profile>my-thing</profile>
      </configuration>
  </plugin>
</plugins>

Or you can use maven properties to configure the plugin, which provides a more flexible way to map multi-module projects in maven onto profiles in fabric8.

For example if you have a multi-module maven project like this:

pom.xml
foo/
  pom.xml
  a/pom.xml
  b/pom.xml
  ...
bar/
  pom.xml
  c/pom.xml
  d/pom.xml
  ...

then in the root pom.xml you might want to define the mvn plugin once like this:

<plugins>
  <plugin>
      <groupId>io.fabric8</groupId>
      <artifactId>fabric8-maven-plugin</artifactId>
  </plugin>
</plugins>

Then in foo/pom.xml you can define the fabric8.profile property:

<project>
  ...
  <properties>
    <fabric8.profile>my-foo</fabric8.profile>
    ...
  </properties>
  ...

Then all of the projects within the foo folder, such as foo/a and foo/b would all deploy to the same profile (in this case profile my-foo). You can use the same approach to put all of the projects inside the bar folder into a different profile too.

At any point in your tree of maven projects you can define a maven fabric8.profile property to specify exactly where it gets deployed; along with any other property on the plugin (see the Property Reference below).

Specifying features, additional bundles, repositories and parent profiles

As of 1.1.0.CR6 we have the OSGi Resolver which if you are deploying a bundle packaging project it will try to automatically choose the best parent profiles, features and bundles for your bundle.

You can also explicitly specify additional configuration in the maven plugin using maven properties...

<properties>
    <!-- fabric8 deploy profile configuration -->
    <fabric8.profile>quickstarts-karaf-cxf-rest</fabric8.profile>
    <fabric8.parentProfiles>feature-cxf</fabric8.parentProfiles>
    <fabric8.features>cxf-jaxrs swagger</fabric8.features>
</properties>

Notice we can pass in a space-separated list of features to include in the profile.

We've used space separated lists for the parent profile IDs, features, repositories and bundles so that its easy to reuse maven properties for these values (for example to add some extra features in a child maven project while inheriting from the parent project).

The OSGi Resolver will add any missing dependencies via analysing your projects dependency tree (ignoring all test and provided scope dependencies).

So to force the OSGi Resovler to ignore a particular dependency in your pom.xml, just mark it as scope provided.

If you wish you can disable the OSGi Resolver completely just specify the fabric8.useResolver property as being false.

Specifying configuration using maven properties on the command line

You can also use maven property values (or command line arguments) to specify the configuration values by prefixing the property name with fabric8..

e.g. to deploy a maven project to a different profile name try:

mvn fabric8:deploy -Dfabric8.profile=cheese -Dfabric8.profileVersion=1.1

By default the project artifacts are uploaded to the maven repository inside the fabric. If you wish to disable this and just update the profile configuration (e.g. if you're already pointing your fabric maven repository to your local maven repository), you can specify fabric8.upload=false as a property:

mvn fabric8:deploy -Dfabric8.upload=false

Adding additional configuration files into the profile

If you create the directory src/main/fabric8 in your local project and add any configuration files or a ReadMe.md file (for documentation) in your project they will get automatically uploaded into the profile too.

e.g. in your project if you run this command:

mkdir -p src/main/fabric8
echo "## Hello World" >> src/main/fabric8/ReadMe.md
mvn fabric8:deploy

Then when your profile will have a ReadMe.md wiki page uploaded.

Adding PID files into the profile

Probably one of the most interesting use cases of the src/main/fabric8 directory, is uploading PID files into your profile. For example you can take my.pid.properties file with the following contents:

foo=bar
baz=qux

...and place it in the src/main/fabric8 directory. After executing mvn fabric8:deploy command, the my.pid.properties file will be uploaded into your profile as a my.pid PID configuration:

> profile-display myprofile
...
Configuration details
----------------------------
PID: my.pid
  foo bar
  baz qux

Using Maven placeholders in PID files

We recommend to add the src/main/fabric8 directory to the list of the resources filtered by Maven. For example:

<build>
  <resources>
    <resource>
      <directory>src/main/fabric8</directory>
      <filtering>true</filtering>
    </resource>
  </resources>
  <plugins>
    <plugin>
      <groupId>io.fabric8</groupId>
      <artifactId>fabric8-maven-plugin</artifactId>
      <version>${fabric8.version}</version>
      <configuration>
        <profile>invoicing</profile>
      </configuration>
    </plugin>
  </plugins>
</build>

With Maven resources filtering enabled, you can use placeholder in your PID files:

jarUrl = mvn:${project.groupId}:${project.artifactId}:${project.version}

Keep in mind that even if Maven resource filtering is not enabled, ${project.groupId}, ${project.artifactId} and ${project.version} placeholders will be still expanded into the project version of the current Maven module.

Specifying the minimum number of required containers for the profile

You can specify the minimum number of instances of a profile that are expected via the fabric8.minInstanceCount property. This value defaults to 1 so that it means the profile you deploy should be instantiated. See the requirements documentation for more details.

What this means is that out of the box if you deploy a profile then view the Profiles tab in the Runtime section of the console, you should see a warning if the profile is not running yet. If you then click on the red button for the missing profile it takes you straight to the Create Container page for the profile. This means you don't have to go hunting around the wiki for the profile to create.

Also if you deploy the autoscale profile then this will automatically create new containers if their requirement count increases.

Specifying Properties

Our recommendation is to use maven properties to configure the fabric8 maven plugin as follows; you just need to add the fabric8. prefix to any property name. This is then easier to work with across multi-maven projects and its easier to inherit values etc.

<project>
  ...
  <properties>
    <fabric8.profile>my-foo</fabric8.profile>
    ...
  </properties>
  ...

Which is equivalent to specifying them on the command line:

mvn fabric8:deploy -Dfabric8.profile=my-foo

If you really want to you can specify the properties (without the fabric8. prefix) in the plugin configuration:

<plugins>
  <plugin>
      <groupId>io.fabric8</groupId>
      <artifactId>fabric8-maven-plugin</artifactId>
      <configuration>
        <profile>${fabric8.profile}</profile>
      </configuration>
  </plugin>
</plugins>

Property Reference

Specifying credentials from command line

The fabric8:deploy goal will by default read the username and password from the local Maven settings.xml file. This may not be desired to store password as plain-text. The option jolokiaUrl can be used to specify the url for the remote fabric server including username and password. For example to use username scott and password tiger then type:

 fabric8:deploy -Dfabric8.jolokiaUrl=http://scott:[email protected]:8181/jolokia

Tip: You can get the jolokia url using fabric:info from the fabric shell.

Generating Karaf shell scripts for each profile

You can also use the fabric8:script goal using the same configuration above to auto-generate a profile create karaf script. The script can then be used from the Karaf shell to create the profile.

From the Karaf shell you can use the shell:source command to run the script, eg:

shell:source file:somepath\target\profile.karaf

The fabric:script creates the script file by default as target\profile.karaf. The name of the output file can be configured using the following options:

Property Reference

Parameter

Description

outputFile

The name of the script file. Is by default target\profile.karaf