Download and install Wildfly

If you don't already have a Wildfly installation, download the JBoss Wildfly archive and unzip it into a known location (e.g., /apps/jboss-wildfly-10.0.0). Please refer to the Wildfly documentation Guide for requirements and installation instructions, and be sure the "$JBOSS_HOME" environment variable is set correctly to the path where Wildfly is installed.

Download and install ModeShape

Download the latest ModeShape Wildfly kit (latest version is 5.4.1.Final). This kit is a ZIP archive that is intended to be unzipped directly into the Wildfly installation. Doing so will not override any of the files in the standard Wildfly installation.

The directory structure of the ModeShape Wildfly kit is as follows:

/docs
   /schema
      modeshape_3_0.xsd
/modules
   /javax/jcr/*
   /org/modeshape/*
   /org/apache/*
/standalone
   /configuration/
      standalone-modeshape.xml
      standalone-modeshape-ha.xml

AS you can see, the kit contains installs the "modeshape_3_0.xsd" into the existing /docs/schema directory, which is where all of the XML schemas for the application server subsystems are defined. The modeshape_3_0.xsd schema defines the entire structure of the ModeShape subsystem fragment in the server's XML configurations.

The kit installs modules for the JCR API (e.g., the javax.jcr packages) for ModeShape and its components. The org.apache module does not exist in the standard Wildfly installation, but ModeShape explicitly avoided using the "main" slot on this module in the off chance that you might have already defined such a module in your installation.

The kit also installs several out-of-the-box configuration files:

• standalone/configuration/standalone-modeshape.xml - contains 2 predefined repositories "sample" & "artifacts"  and should be used when running a single Wildfly instance.

• standalone/configuration/standalone-modeshape-ha.xml - contains the same "sample" repository but configured in clustered mode.

Finally, the kit also deploys the "modeshape-rest", "modeshape-webdav", "modeshape-cmis" and "modeshape-explorer" web applications via the above configuration files. The "modeshape-rest", "modeshape-webdav", "modeshape-cmis" web applications allow users to interact with ModeShape via the REST, WebDAV and CMIS APIs respectively. The "modeshape-explorer" application provides a GUI of the installed repositories. If you don't want any of these applications to be deployed when the server starts up, comment out or remove the following configuration fragments:

<subsystem xmlns="urn:jboss:domain:modeshape:3.0">
   <!--The list of web applications that is packaged inside the kit and should be deployed when the subsystem starts up-->
   <webapp name="modeshape-rest.war"/>
   <webapp name="modeshape-webdav.war"/>
   <webapp name="modeshape-cmis.war"/>
   <webapp name="modeshape-explorer.war"/>

Add users and roles

For example, to add an admin user with the admin password, you would first run:

 add-user.sh -a admin admin

Then you need to edit the configuration/application-roles.properties files and add some roles for the user.  Add Statement,  admin=connect,admin.

This behavior is controlled by the configuration of the default modeshape-security security domain:

  <security-domain name="modeshape-security" cache-type="default">
    <authentication>
      <login-module code="RealmDirect" flag="required">
         <module-option name="password-stacking" value="useFirstPass"/>
      </login-module>
    </authentication>
   </security-domain>

If this is not desired, you can just change this by editing the above section in the standalone-modeshape.xml configuration file. For example, if one wanted to also support the old (pre 4.0) modeshape-users.properties and modeshape-roles.properties, one would edit the security domain like:

 <security-domain name="modeshape-security" cache-type="default">
   <authentication>
    <login-module code="UsersRoles" flag="required">
      <module-option name="usersProperties" value="${jboss.server.config.dir}/modeshape-users.properties"/>
      <module-option name="rolesProperties" value="${jboss.server.config.dir}/modeshape-roles.properties"/>
    </login-module>
    <login-module code="RealmDirect" flag="optional">
      <module-option name="password-stacking" value="useFirstPass"/>
    </login-module>
   </authentication>
 </security-domain>

Run Wildfly with the sample configuration in standalone mode

At this point, you've installed ModeShape into your Wildfly installation, and it's ready to be used. Let's run the server in standalone mode with the provided "standalone-modeshape.xml" configuration:

$ bin/standalone.sh -c standalone-modeshape.xml

The server process will output a few dozen lines of messages, including one that says something similar to:

...
INFO  [org.jboss.as] (Controller Boot Thread) WFLYSRV0025: WildFly Full 10.0.0.Final (WildFly Core 2.0.10.Final) started in 13410ms - Started 656 of 965 services (416 services are lazy, passive or on-demand)

At this point, the server is running and ready to accept requests at http://localhost:8080. If you want to see the "sample" repository in action, use your browser to go to http://localhost:8080/modeshape-rest or http://localhost:8080/modeshape-webdav to see http://localhost:8080/modeshape-rest/the information about the running repositories.

To stop the server, simply hit CTRL-C in the terminal where WildFly is running, and it will shutdown immediately but gracefully.

Run WildFly with the sample configuration in clustered standalone mode

If you want the check out how a ModeShape repository can be clustered, you can start a couple of WildFly nodes locally using the "standalone-modeshape-ha.xml" configuration file:

$ bin/standalone.sh -c standalone-modeshape-ha.xml

$ bin/standalone.sh -c standalone-modeshape-ha.xml -Djboss.socket.binding.port-offset=100

As you can see, if you want to run several clustered nodes locally, there is one important property you need to provide:

• jboss.socket.binding.port-offset - a numeric value which will be used as an offset value for the various socket ports each instance opens. For example, by default the HTTP socket listens on port 8080. When passing the value 100, that Wildfly node will listen for HTTP connections on port 8180.

Add optional dependencies

In certain cases, you may find that additional dependencies are required to be installed into the Wildfly server for certain ModeShape features to be available(for example the Mongo, Cassandra and S3 binary stores).
In this case you need to make sure you create separate modules for those dependencies and install those modules into JBoss AS. To make sure the modules contain the correct artifact versions, you can use the ModeShape AS BOM:

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.modeshape.bom</groupId>
      <artifactId>modeshape-bom-jbossas</artifactId>
      <version>5.1.0.Final</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

You can read more about JBoss modules here.

After creating the extra server modules with the correct artifact versions, you need to make sure that ModeShape can access these modules. To do this, you'll have to configure your repository so that it's aware of the external (additional) modules. To see how to do this see the configuration part of the documentation.

Next steps

Feel free to play with the sample repository through the REST API. However, since this is really just a sample configuration, we'll next see how to add ModeShape to other Wildfly configurations.