Version 7

    On January 29th, 2011, an official Magnolia release with ModeShape support has been released, so this article is not worth reading anymore. But I am leaving it here to document the history.



    In JBoss Community Team, we are using Magnolia for the "static" content of We are not using just pure "out-of-the-box" Magnolia, but we developed some extensions (modules) for our specific needs. When we had migrated JBoss Community downloads to, the need to allow our Magnolia users to browse this storage and insert links to files into their content the same way as they can do it with other content in Magnolia. By default, Magnolia is based on Jackrabbit JCR implementation, which doesn't allow such "magic" - it is pure JCR implementation.


    But we realized we have an "in-house" JCR implementation, that is not just an another silo for information, but it has many interesting features and it become mature and reliable in the meantime - ModeShape. So we decided to eat our own dogfood, and started the work on migrating Magnolia from Jackrabbit to ModeShape, and now you can taste first fruits of this effort reading and testing this guide.



    Magnolia CMS is an open-source Web Content Management System that focuses on providing an intuitive user experience in an enterprise-scale system.


    ModeShape is a JCR 2.0 (JSR-283) implementation that provides access to content stored in many different kinds of systems.

    Basic version (with InMemory store)

    TODO: why InMemory, what is InMemory, non-persistent, ...


    1. Install and configure Tomcat 5.5.27 (or newer) from
    2. Download magnolia-empty-webapp-4.3.6-modeshape-{timestamp}.war from
    3. Download ModeShape 2.1.0 or newer from (JAR file named -all-with-dependencies), or get source code from and build it on your own.

    Unpack Magnolia

    1. Create new directory named "magnolia-author" in the $TOMCAT_HOME/webapps directory.
    2. Copy the content of above downloaded magnolia-empty-webapp war file into that new directory.

    Copy ModeShape-JCR libs

    Find modeshape-jcr-2.1.0.Final-with-dependencies.jar in the ModeShape file you've downloaded (or builded) in the above step, and copy its content (~16 JAR files) to the magnolia-author/WEB-INF/lib directory.

    Replace jcr-1.0.jar with jcr-2.0.jar

    Remove jcr-1.0.jar from WEB-INF/lib directory.
    Get jcr-2.0.jar (e.g. from and place it to the WEB-INF/lib directory.

    Add oswego-concurrent library

    From, download concurrent-1.3.4.jar and place it into WEB-INF/lib directory.

    Get JBoss Security libraries

    Get following JAR files, e.g. from the Maven repository:

    • jboss-common-core-2.0.2.GA.jar
    • jboss-idtrust-2.0.2.CR1.jar
    • jboss-jaspi-api-1.0.0.GA.jar
    • jboss-javaee-5.0.0.Beta3.jar
    • jboss-jaxs-api-
    • jboss-jmx-4.2.1.GA.jar
    • jboss-logging-log4j-2.0.2.GA.jar
    • jboss-logging-spi-2.0.5.GA.jar
    • jboss-reflect-2.0.0.CR1.jar
    • jboss-security-acl-impl-2.0.2.SP6.jar
    • jboss-security-spi-bare-2.0.2.SP6.jar
    • jboss-security-spi-2.0.2.SP6.jar
    • jboss-sunxacml-2.0.2.GA.jar
    • jbosssx-bare-2.0.2.SP6.jar
    • jboss-xacml-2.0.2.GA.jar
    • jbossxb-2.0.0.CR15.jar


    and copy them to the WEB-INF/lib directory.

    Get Shaped-Magnolia jar file

    Get attached shaped-magnolia-0.0.1-SNAPSHOT.jar and place it to the WEB-INF/lib directory.

    Configure Magnolia

    Note: All directory/file references starts from $TOMCAT_HOME/webapps/magnolia-author/WEB-INF directory, unless otherwise stated.

    Configure JAAS

    Add following lines to the config/jaas.config file:


    {code}modeshape-jcr { required usersProperties="" rolesProperties="" name="1.1" succeed=true throwEx=false ;



    Create files named "" and "" in tha "classes" directory, with following content:




    (The content is the same for both files - defines "admin" user with password "admin", the defines that user "admin" has "admin" role.)

    Configure repositories

    Copy attached magnolia.cnd file to the config/repo-conf directory.

    Copy attached magnolia-bundle-inmemory-search.xml file in config/repo-conf directory.


    In the config/default/repositories.xml file, replace


    <Repository name="magnolia" provider="info.magnolia.jackrabbit.ProviderImpl" loadOnStartup="true">


    line with the


    <Repository name="magnolia" provider="org.jboss.labs.magnolia.modeshape.ProviderImpl" loadOnStartup="true">


    In the config/default/ file, change the magnolia.repositories.jackrabbit.config property from WEB-INF/config/repo-conf/jackrabbit-bundle-derby-search.xml to WEB-INF/config/repo-conf/modeshape-bundle-inmemory-search.xml


    Optionally, change also the property from false to true (to perform the Magnolia bootstrap automatically).


    START TOMCAT and try http://localhost:8080/magnolia-author/ in your browser after a while.


    Showing filesystem content

    Now you have Magnolia CMS running on ModeShape - but our original goal was not only to replace one JCR provider (Jackrabbit) with another, but to add some new functions, like displaying of the filesystem content etc. So let's continue the configuration:

    Repository configuration

    1. Stop Tomcat you started at the end of previous section.


    2. Create new directory on your filesystem (or choose the existing one) e.g. /tmp/filesystem/files, where you'll later point the Modeshape's filesystem connector. If you want, you can populate this directory a bit. (In fact, /tmp/filesystem directory will represent a repository, and files subdirectory will represent a workspace named "files", which we will map to "downloads" name later.)


    3. Get modeshape-connector-filesystem JAR file from your Modeshape package (or from Maven repo) and place it to the WEB-INF/lib directory (this library has no dependencies at the moment of writing this guide).


    4. In the WEB-INF/config/repo-conf/modeshape-bundle-inmemory-search.xml file, uncomment

    <mode:source jcr:name="disk" ... 

    part, and replace


    line with


    line in the <mode:repository jcr:name="magnolia"> part.


    5. In the WEB-INF/config/default/repositories.xml file, add line

    <Map name="config" repositoryName="magnolia" workspaceName="config" />

    in the <RepositoryMapping> part, and line

    <workspace name="downloads" />

    in the <Repository name="magnolia" ... part.


    6. Start Tomcat.

    Magnolia configuration

    1. Point your browser to http://localhost:8080/magnolia-author/ and then login to Magnolia as superuser.


    2. Go to Security > Roles (left column), choose "superuser" role and click Edit. Select "Access control list" tab, switch to "Downloads" in workspaces dropdown list, and set Read/Write access for / node and subnodes. Click Save.

    This will allow users in superuser role to see (anch change) the content of the "Downloads" workspace we defined in previous section.


    3. Log out and log in again to make access rights changes active.

    Now if you have some content in the /tmp/filesystem/files directory defined above, you can see it using Tools > JCR Queries menu. Select "downloads" repository, set query language to xpath, and write //* query into the textfield. After clicking Execute, you'd see JCR representation of the filesystem in the Result field.


    4. Now we will continue by defining our own JCR Browser - you can find details here, but I've prepared a short way for you:

    Go to Configuration menu and open /modules/adminInterface/trees node. Right click on trees and select "Import from XML". Then choose attached config.modules.adminInterface.trees.downloads-jcr.xml file and click "Import".

    Open /modules/adminInterface/config/menu/tools node and import attached file.


    Wait few second for adminInterface module restart, then go to Tools menu, and you should see new "Downloads browser" menu item. Click it, and you will see the filesystem.


    NOTE: At the moment of writing this guide, is just a "demo class" based on JcrBrowserTreeConfiguration class. It just allows you to see the content and delete files, although the menu shows more options.


    Adding persistence