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.1.0.CR5: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.1.0.CR5: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

You can also specify additional configuration in the maven plugin like this:

<plugins>
  <plugin>
    <groupId>io.fabric8</groupId>
    <artifactId>fabric8-maven-plugin</artifactId>
    <configuration>
      <profile>my-rest</profile>
      <features>fabric-cxf-registry fabric-cxf cxf war swagger</features>
      <featureRepos>mvn:org.apache.cxf.karaf/apache-cxf/${version:cxf}/xml/features</featureRepos>
    </configuration>
  </plugin>
</plugins>

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).

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 configuration using maven properties

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 Properties

The following properties can be specified as elements inside the <configuration> section of the plugin in your pom.xml. e.g. the profile configuration can be passed like this:

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

Or you can specify these properties using the command line or maven build properties - prefixing the property names with fabric8. for example to set the profile name, you could add this to your pom.xml..

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

Or specify the command line:

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

Property Reference

Parameter Description
profile The name of the fabric profile to deploy your project to. If not specified it defaults to the groupId-artifactId of your project.
abstractProfile Whether the profile is marked as abstract. Defaults to false
serverId The server ID used to lookup in ~/.m2/settings/xml for the <server> element to find the username / password to login to the fabric. Defaults to fabric8.upload.repo
jolokiaUrl The Jolokia URL of the Fabric console. Defaults to http://localhost:8181/jolokia
profileVersion The profile version in which to update the profile. If not specified it defaults to the current version of the fabric.
baseVersion If the version does not exist, the baseVersion is used as the initial value of the newly created version. This is like creating a branch from the baseVersion for the new version branch in git.
parentProfiles Space separated list of parent profile IDs to be added to the newly created profile. Defaults to karaf.
features Space separated list of features to be added to the profile. e.g. a value could be this to include both the camel and cxf features: <features>camel cxf</features>
featureRepos Space separated list of feature Repository URLs to be added to the Profile. Of the form mvn:groupId/artifactId/version/xml/features
bundles Space separated list of additional bundle URLs (of the form mvn:groupId/artifactId/version to be added to the newly created profile. Note you do not have to include the current maven project artifact; this configuration is intended as a way to list dependent required bundles.
minInstanceCount The minimum required number of instances of this profile. This defaults to 1 if you do not specify it. See the requirements documentation for more details.
upload Whether or not the deploy goal should upload the local builds to the fabric maven repository. You could disable this step if you have configured your fabric maven repository to reuse your local maven repository. Defaults to true.
ignoreProject If set to true then this maven project is ignored when goals like fabric8:deploy are invoked from a parent project. Defaults to false.
includeArtifact If set to false then the maven artifact of the project is ignored; its not uploaded and not added/updated in the profile. Defaults to true.
profileConfigDir The folder in your maven project containing configuration files which should be deployed into the profile along with the artifact configuration. This defaults to src/main/fabric8. Create that directory and add any configuration files or documentation you wish to add to your profile.
includeReadMe Whether or not to include the project readme file (if exists). Notice that if there is already a readme file in profileConfigDir, then that file is included, and not the project readme file. Defaults to true.
webContextPath For web applications (projects with war packaging) this property specifies the context path to use for the web application; such as "/" or "/myapp". This value defaults to the archetype id.
replaceReadmeLinksPrefix Used by the zip goal, which allows to prefix any links in the readme.md files to make the links work in both github and as links in the fabric wiki. For example the fabric quickstarts uses this, by prefixing with /fabric/profiles/quickstarts/.
useResolver Whether or not the OSGi resolver is used for bundles or karaf based containers to deduce the additional bundles or features that need to be added to your projects dependencies to be able to satisfy the OSGi package imports. Defaults to false.

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.