Boost Your Platform with the New eXo Add-ons Manager

Ho, Ho, Ho, eXo Tribe!!!

Isn’t it the season to give gifts to your beloved friends and family? I’m not Santa Claus but I will give you a gift for Xmas, which I hope you’ll enjoy.

In Platform 4.0 we introduced a basic extensions manager, the extension [sh|bat] script, which can be used to install and uninstall various extensions provided by your platform distribution (CRaSH, eXo IDE, …).

At the end of November, while we were traveling with Frédéric and Patrice from France to our eXo office in Vietnam, we thought about how to improve this feature to ease the sharing of the many add-ons, contributed by you, our community.

After a few days of work, I developed a prototype, which I’ve just released as version 1.0.0-alpha-2 (thanks to Frédéric for the bug report for version 1.0.0-alpha-1). There are still many things outstanding, but if you like it like us, you may see it in a future version of Platform.

Let’s take a tour…

Prerequisites

The add-on manager requires Platform 4+ and at the moment I’m testing it with various combinations of environments from Platform 4.0.1 to the latest 4.1.0, which is in development:

Installation

To install the add-on manager, just download it and extract the content of the archive into your Platform installation directory. This will add to the root two new scripts (addon.sh and addon.bat) and a new directory addons containing a jar (addons-manager.jar).

To validate your installation, on Windows just launch the script addon.bat or addon.sh on other systems. Use the option –help to display the help messages of the command line program.

addon.sh --help

For this article, I’ll use Platform 4.0.3 community edition on Mac OS (and so I’ll use the addon.sh script).

List available add-ons

The main goal of this new add-on manager is to make it easier to install add-ons into your platform. We will start by listing all of the available add-ons

addon.sh --list

We have referenced various known extensions in an index and the program displays them. Using this form, you can ask to Patrice to reference a new add-on or a new version of an existing add-on.

We also reference development versions (snapshots) of add-ons but we don’t propose them by default as they may be unstable. To display them, just add the option –snapshots

addon.sh --list --snapshots

Install an add-on

To install the latest released version of the awesome chat add-on, for example, we just call:

addon.sh --install exo-chat-extension

To install the latest version of an add-on including development versions we call:

addon.sh --install exo-chat-extension --snapshots

Oh right ! By default, we don’t want you to overwrite an existing version without a warning. Let’s enforce it with the option –force

addon.sh --install exo-chat-extension --snapshots --force

We just replaced version 0.8.0 by the development version 0.8.1-SNAPSHOT.

Let’s now reinstall a specific version (0.8.0-beta1) using the syntax addonId:addonVersion

addon.sh --install exo-chat-extension:0.8.0-beta1 --force

Uninstall an add-on

To uninstall an add-on we just call:

addon.sh --uninstall exo-chat-extension

How can I reference my own add-ons?

While you are developing an add-on or if you just don’t want to reference it in the global index, you can attach you own list of add-ons to the Platform.

Let’s imagine I’m working on the staging-extension add-on, and I’m deploying it in my local repository with Apache Maven.

To install it using the add-on manager, I just have to create a file $PLATFORM_HOME/addons/list.json (NOTE 2014/12/02 : $PLATFORM_HOME/addons/local.json in add ons manager 1.0.0+) with this minimal content:

[
 {
   "id": "exo-staging-extension",
   "version": "2.3.0-SNAPSHOT",
   "name": "Staging Extension",
   "description": "allows to stage your content before deploying it into production",
   "downloadUrl": "file://../../.m2/repository/org/exoplatform/addons/staging/staging-extension-packaging-extension/2.3.0-SNAPSHOT/staging-extension-packaging-extension-2.3.0-SNAPSHOT.zip",
   "vendor": "eXo platform",
   "license": "LGPLv3",
   "supportedDistributions": ["community","enterprise"],
   "supportedApplicationServers": ["tomcat","jboss"]
 }
]

And then I can install it with:

addon.sh --install exo-staging-extension:2.3.0-SNAPSHOT --force

Take care, because at the moment the download URL only supports a relative path from the add-on directory of your Platform installation.

For now, an add-on archive is just a zip file with all the jar and war files required by your add-on. The script automatically copies them to wherever necessary.

What’s next?

Frédéric is trying to summarize all the requirements in a specification. Don’t hesitate to give us your feedback and to comment it. We are all ears.

If you encounter any issues with the current version, don’t hesitate to report them in the tracker. If you want to contribute, don’t hesitate to have a look at the code. There is a README to explain how to build and test the project. I’ll review with pleasure all pull requests.

I wish you a Merry Xmas!

Arnaud