Configuring global Modules and Directories in WildFly

WildFly lets you share a single module across all your Enterprise Applications. This means you can add your module to your application stack, with no deployment configuration. There are two ways to achieve it: Using global directories and using global modules. Let’s see both options.

Configuring Global directories for your modules

Since WildFly 19 and JBoss EAP 8 you can to define global directories for your modules. By using global directories you can add a set of libraries which are in a single directories. Another common use case for global directories is when your library JAR file often change in their names.

You can configure global directories in the ‘ee’ subsystem which allows the configuration of a global directory to scan for dependencies. This module dependency is added as a system dependency on each deployed application.

For example, you can define a Global Directory from the Web Management Console by selecting the ee subsystem | Global Modules | Add :

wildfly global modules

On the other hand, here is how to configure as global directory the folder lib relative to JBOSS_HOME directory using the CLI:

/subsystem=ee/global-directory=my-common-libs:add(path=lib, relative-to=jboss.home.dir)

You can also use an absolute path in your global module. For example:


When you define a global-directory, WildFly createss a module which has a Jar Resource loader for each jar file in this directory and its subdirectories.

For example, suppose you have configured one global directory pointing to the following directory tree:


The JBoss Modules module generated after scanning this global-directory will be equivalent to the following module.xml:

<module xmlns="urn:jboss:module:1.5" name="">
        <resource-root path="/home/jboss/tools/libs/commons-math3-3.6.1.jar"/>
        <resource-root path="/home/jboss/tools/libs/poi-4.1.1.jar"/>

        <module name="javaee.api"/>

If you include property files in your global directory, then you can also access them using the context ClassLoader of your current thread:


WARNING: The module created from the shared directory is loaded as soon as the first application is deployed in the server after creating the global-directory. That means, if the server is started/restarted and there are no applications deployed, then the global directory is neither scanned nor the module loaded. Any change in any of the contents of the global-directory will require a server reload to make them available to the deployed applications.

Configuring Global modules

The other option, available also for older WildFly release, is to use Global modules. A Global module is a set of WildFly Modules that is available as dependency for every Jakarta EE application running on WildFly. Such dependencies allows Java EE deployments to see the classes exported by the global modules.

Firstly, you need to add the module on WildFly. Then, you can add it as global module. For example, to add javassist to all deployments you can use the following XML configuration:

<subsystem xmlns="urn:jboss:domain:ee:1.0" >            
    <module name="org.javassist" slot="main" />            

The only mandatory attribute is the module name, the slot attribute defaults to main, and both define the JBoss Module ID to reference.

The optional annotations attribute indicates if a pre-computed annotation index should be imported from META-INF/jandex.idx . Defaults to false.

The optional services attribute indicates if any services exposed in META-INF/services should be available to the deployments class loader. Defaults to false.

The optional meta-inf attribute, which defaults to true, indicates if the Module’s META-INF path should be available to the deployment’s class loader.

Global Modules vs Global directories

Using the Modules directory has the advantage to make more flexible your configuration: if you update the module’s jar file names you don’t need to update also the module.xml. This makes this option ideal for development and testing.

Using Global directory, on the other hand, has the advantage of not including any file system link (hard or symbolic) to the Classloading process. This makes this option ideal for production environment.