ModeShape can be installed into an existing JBoss Wildfly server. If you already have one, then you also have the $JBOSS_HOME environment variable set to the installation location.
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 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:
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:
|Starting with version 4.0, ModeShape integrates with Wildfly's default Application Security Realm and does not provide any pre-configured users & roles out-of-the-box. Instead, users & roles are added via Wildfly's add-user utility.|
For example, to add an admin user with the admin password, you would first run:
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:
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:
|In addition to the default repository roles: admin, readwrite and read the role connect is required if a user wants to access any of the above described web applications that are deployed in Wildfly. Also, beware of spaces: do not use spaces before/after the commas as that will create incorrect role names.|
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:
The server process will output a few dozen lines of messages, including one that says something similar to:
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.
|The resulting page is a JSON file that is difficult to read without formatting it in an editor. At this point, the content of the response is not important, but it simply shows that ModeShape is running with a "sample" repository.|
To stop the server, simply hit CTRL-C in the terminal where WildFly is running, and it will shutdown immediately but gracefully.
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:
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.
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:
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.
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.