Page tree
Skip to end of metadata
Go to start of metadata

I intend to describe a complete step by step description of preparing a magnolia project based on maven dependency management / structuring. I start off with the official empty magnolia archetype and build the project to have separate maven modules with author and public instances. An additional module would be the one that holds the templates / structure for the site. This one first gets to be a "lightmodule" then inserted into the maven project structure. I don't want to get deep into configs but just very basic things to get started.

This is a learner's guide, I'm actually working towards this goal and update this How-to as I go. So, DANGER. You have been warned: this article is from a complete newbie to Magnolia. Although I would like to receive feedback and help from experienced users and improve this article so that this warning paragraph could be softened, and even stated that it follows the best practices and when not why not.

Step-by-step guide

Get your startup skeleton.

  1. Run the bellow command, selecting then 2 as for project archetype, then provide the group name like and artifactID like HowTo

    mvn org.apache.maven.plugins:maven-archetype-plugin:2.4:generate -DarchetypeCatalog=

  2. Make a copy of the x-webapp directory naming x-webapp as author and the other as public, modify artifact names, pom.xml accordingly

    1. in the child pom.xml files:
      - rename artifactId: author / public
      - remove <name>

    2. adjust parent pom.xml accordingly
      - rename x-webapp to author and add public

    3. To get a working author and public instance with default configs, just name the author magnoliaAuthor and the public magnoliaPublic. This way it will load the default settings, so that the configs bellow are not required.
  3. Get a web.xml to both instances {author,public}\src\main\webapp\WEB-INF\ based on:
    1. Example web.xml:

      <?xml version="1.0" encoding="UTF-8"?>
      <web-app xmlns="" 
          <distributable />
              <display-name>Magnolia global filters</display-name>
              <description>Vaadin production mode</description>
          <!-- These are the default paths searched for magnolia configuration. Uncomment if you need to customize these. Your container might also do its own variables substitution here. Tomcat, for instance, allows you to use system properties, such as ${user.home}. -->
          <!-- <context-param> <param-name>magnolia.initialization.file</param-name> <param-value> WEB-INF/config/${servername}/${contextPath}/, WEB-INF/config/${servername}/${webapp}/, WEB-INF/config/${servername}/, WEB-INF/config/${contextPath}/, WEB-INF/config/${webapp}/, WEB-INF/config/default/, WEB-INF/config/ </param-value> </context-param> -->
  4. By now we have two working author instances, but before activating them it would make sense to first understand how to create a module that would be presented to site visitor. We can understand a module's structure from:

    1. Can be a maven module structure before it is built (file system)

    2. Can be a module under $magnolia.resources.dir (also called a light module)

    3. In order to setup an empty magnolia.resources.dir we need a src/main/webapp/WEB-INF/config/default/ file based on:
      3. A sample built based on the above articles:
        # RESOURCES. The directory to expose file system resources from
        # Repository configuration
        magnolia.repositories.home = ${magnolia.home}/repositories
        magnolia.repositories.config = WEB-INF/config/default/repositories.xml
        magnolia.repositories.jackrabbit.config = WEB-INF/config/repo-conf/jackrabbit-bundle-derby-search.xml = ${magnolia.home}/history
        magnolia.cache.startdir = ${magnolia.home}/cache
        # The directories in which the bootstrap files are searched
        magnolia.bootstrap.dir = WEB-INF/bootstrap/author WEB-INF/bootstrap/common
        # Repository connection
        magnolia.connection.jcr.userId = admin
        magnolia.connection.jcr.password = admin
        # Defining the instance as author instance
        # Only used for the initial installation.
        # Afterwards configuration in the config repository is used.
        # The value is saved in /server/admin
        # Switch to false to enhance the performance of Javascript generation, to true to disable caching and reload after changes in classpath from IDE
        # Set to true if bootstrapping/update should be performed automatically
        # Logs
        # Activate UTF-8 support to pages
        # Some modules contain optional sample content. They will check this property to decide if they should install
        # the sample data
        # Location of the file containing both the private and the public keys used to verify authenticity of activation requests
        # This file is generated if not present${magnolia.home}/
        # Sticker
      4. In order to have the ability to setup light modules separately for the public and author instances, one needs to define magnolia.home differently and resolve the other required paths form it:
        1. magnolia.home=c:/magnolia/public

        2. magnolia.bootstrap.dir = WEB-INF/bootstrap/public WEB-INF/bootstrap/common 

        3. magnolia.bootstrap.authorInstance=false 

        4. magnolia.ui.sticker.environment=Public

  5. Now we can start up our IDE, import the Tomcat 9 server, increase the start timeout with some 999-s to be sure it doesn't get killed for slow server startup (smile).

    1. import maven project, add to server, launch server with author, public webapps
    2. bootstrap, start up magnolia from browser, like: http://localhost:8080/author and http://localhost:8080/public
    3. We can determine on which instance we are actually from the sticker or by going to the about page (see Tools > About Magnolia)
  6. Check the change from the "public" maven module from author to public magnolia instance
    1. config: /server/admin to false
    2. security: edit the roles of anonymous
      1. Access control tab
        1. website: grant read-only access to all website content
      2. Web access tab
        1. grant Get & Post access to all URLs 
        2. but deny access to 
          1. AdminCentral (/.magnolia & /.magnolia/*)
        3. see default permissions for instances:,publicinstance)
    3. ?Add the public-user-registration-base role (read in the docs [see point 7], but should it be a new role without settings, what is that good for?)
    4. Set /modules/ui-admincentral/virtualURIMapping/default/toURI to your start page: redirect:/
      1. ?as the above things are all set by, couldn't this be also set from there?
    5. Verify the instance type in the About Magnolia app.
  7. Set the publish-subscribe relationship: (before 5.6 subscribers were used, now they are called recievers)
    1. Configuration > /modules/publishing-core/config/
      1. in the "recievers" content node add a content node as "public" that is the name for the public instance or use the default and rename it
        1. add the following properties to the content node defined above
          1. url: http://localhost:8080/public
          2. enabled: true
        2. add workspace content node inside the instance, ex.: "websiteWorkspace" with properties:
          1. workspace: webiste
          2. fromPath: /public
          3. toPath: /public
  8. Activation security, resolve mismatching keys
    1. ?The properties file config probably resolved this already.
    2. generate a new public key and copy it to the public instance:
      1. Tools / Publishing tools / copy the current public key
      2. Sign into the public instance (http://localhost:8080/public/.magnolia/admincentral) and open the Configuration app
        1. Paste they key to Configuration > /server/activation/publicKey
  9. First build a site template light module
    1. try to create just a light module, be it c:\magnolia for this example
      1. install magnolia cli: npm install @magnolia/cli -g
      2. check if ok: mgnl help
    2. in cmd go to c:/magnolia that is the resource.dir defined in, create a module with magnolia cli: At that page I have commented with what I'm stuck.
  10. Create/Transform to maven module the previously built light module


  1. Perhaps it would be easier for you to download a tomcat bundle from if you need both an author and a public.

  2. Will consider the other way around and update it when I will get to the point of finishing with a demo project. Doing it in spare time...