Module Management

Modules in Jahia are a powerful concept.  Designed to be plug&play, modules allow you to create applications sourcing content from Jahia, create template sets that provide the digital framework for your web projects or create extensions to the Jahia product.  Modules are easy to create, and can be hot deployed at any time.   

Before you begin

Jahia modules rely on Java and Maven. The key requirements are as follows:

• Access to a local Jahia system or the free cloud trial from Jahia
• Oracle JDK 11 or OpenJDK 11
• Maven 3.3+

What you will learn

This tutorial is intended to get you started working with modules.  

• module creation,
• deployment
• some automation principles

About modules

Modules can be used for a variety of purposes, from extension to complete applications, in Headless CMS and Web project use cases. At the most basic level a module is a jar file, generated from a Maven project, embedding a Spring context and able to run on an OSGI platform.

A Jahia module relies on the Java ecosystem:

• jar file generated from a Maven project
• embeds a Spring context
• runs on an OSGi runtime platform

Modules can embed any number of the following items.:

• Content type definitions
• Content type views (HTML)
• Static assets (Javascript, CSS, JSON, CSV…)
• Content
• Site templates
• Java classes
• Workflows
• Automated rules
• Roles and permissions

Create a module

Modules can be created via the Jahia Studio, or in the command line interface (CLI). This tutorial will focus on the CLI approach.

To create a new module:

Open a shell terminal (Windows, Linux or MacOS) and run the following command:

mvn archetype:generate -Dfilter=org.jahia.archetypes:

The CLI will prompt you for details:

• Pick the project type '2', jahia-module-archetype
• Pick the latest version of the project type available
• Choose 'n' to the next question, you want to specify the project name and version yourself
• groupId: org.jahia.foo
• artifactId: myFirstModule
• version: leave as default (hit enter)
• package: org.acme.modules
• jahiaVersion: 8.0.0.0
• moduleName: My First Module

A folder myFirstModule was created.

Build a module 

Generate a jar file for deployment.

Enter the myFirstModule folder and run mvn clean install. You should see:

[INFO] BUILD SUCCESS

Your new Jahia module can be found in target/myFirstModule-1.0-SNAPSHOT.jar.

Deploy a module by REST API

Modules can be deployed from the Jahia administration interface by uploading the Jar file directly. However, our favourite option is to use the module management REST API, since it allows a full automation of the platform, and can be used by your favorite CI/CD tool to automatically deploy code.

In your favourite CLI from the myFirstModule/target folder:

curl -s --user root --form bundle=@myFirstModule-1.0-SNAPSHOT.jar --form start=true https://demo.cloud.jahia.com/modules/api/bundles

The module name and the hostname of the instance needs to be changed.

The following response should appear:

{"bundleInfos":[{"groupId":"org.acme.modules","symbolicName":"myFirstModule","version":"1.0.0.SNAPSHOT","key":"org.acme.modules/myFirstModule/1.0.0.SNAPSHOT"}],"message":"Operation successful"}

Module life cycle

Modules have a life cycle of their own, and can be stopped, started, undeployed and versioned. Modules are considered as autonomous applications deployed inside Jahia, which allows you to manage them without impacting the rest of the platform.

Modules can be stopped, started and undeployed via REST API calls.  Several examples follow.

Stop:

curl -s --user root --data --request POST https://127.0.0.1:8080/modules/api/bundles/org.acme.modules/myFirstModule/1.0.0.SNAPSHOT/_stop

Start:

curl -s --user root --data --request POST https://127.0.0.1:8080/modules/api/bundles/org.acme.modules/myFirstModule/1.0.0.SNAPSHOT/_start

Uninstall:

curl -s --user root --data --request POST https://127.0.0.1:8080/modules/api/bundles/org.acme.modules/myFirstModule/1.0.0.SNAPSHOT/_uninstall

Activate a module on a site

Once deployed on Jahia, modules can be activated on specific sites. This will allow for a granular deployment of features across a multi-site platform.

To activate a module on a site, follow this path:

Administration > Systems Components > Modules

Look for the module myFirstModule and click on this name. The following section will list all sites available, and allows you to activate this module on specific sites.

Module development

Jahia Modules are regular Maven projects inheriting from the following artifact:

    <parent>
        <artifactId>jahia-modules</artifactId>
        <groupId>org.jahia.modules</groupId>
        <version>8.0.0.0</version>
    </parent>

A Jahia module can easily be imported in your favorite IDE (Eclipse, Intellij…) and provides dependency resolutions for all assets of the module.