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

Applying the Maven-based approach to create a custom webapp with STK with Magnolia's magnolia-enterprise-pro-webapp , this tutorial explains how to create custom webapps which include the Standard Templating Kit (STK). We recommend using Maven to handle module dependencies. However, you can can adapt a webapp manually by adding JAR files. We will explain this in the second part of the tutorial.

Standard Templating Kit (STK) was deprecated on September 15, 2017 and will reach end of life on December 31, 2018. See End-of-life policy - STK. If your project still relies on STK you can use the module. However, Magnolia is no more providing preconfigured webapps and bundles with the STK. You have to build one yourself.

Using Maven to generate the webapp

We assume that you have at least a basic knowledge of Maven. To tailor a webapp, you typically start with an existing webapp where you add (and probably exclude) other modules. The page creating a custom bundle explains a scenario which starts with the Magnolia empty-webapp . In this tutorial you will create a custom webapp based on the magnolia-enterprise-pro-webapp .

Maven setup

Since you will build a webapp based on the magnolia-enterprise-pro-webapp , make sure you have the proper Maven settings providing access to the Magnolia enterprise repository. 

 Click here to expand to follow the test scenario

To check your settings, follow these steps:

open a terminal, change to a temporary directory and clone the documentation-check-maven-settings module from magnolia git:

cd tmp/
git clone https://git.magnolia-cms.com/git/documentation/documentation-check-maven-settings.git

The git command should produce the following (or a similar) output:

Cloning into 'documentation-check-maven-settings'...
remote: Counting objects: 15, done.
remote: Compressing objects: 100% (8/8), done.
remote: Total 15 (delta 0), reused 0 (delta 0)
Unpacking objects: 100% (15/15), done.
Checking connectivity... done.

Now change into the cloned module and build the project with the -U option:

cd documentation-check-maven-settings/
mvn clean install -U

Maven will print out all the downloaded artifacts. At the end it should display the "BUILD SUCCESS" message:

[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 2.467 s
[INFO] Finished at: 2014-12-11T11:54:27+01:00
[INFO] Final Memory: 22M/184M
[INFO] ------------------------------------------------------------------------

If you couldn't build documentation-check-maven-settings , please read Maven setup and modify your settings accordingly. If you were successful, read on. (Lächeln)

Creating a custom bundle using a Maven archetype

In this section, you will:

  1. Run a Maven command to produce an archetype.
  2. Adapt the result from step 1 to make sure that the webapp inherits from the magnolia-enterprise-pro-webapp .
  3. Add the STK modules.
  4. Set the pro widgetset
  5. Build the webapp with Maven. 

Step 1: Using the Maven archetype command

Open a shell and move to a working directory of your choice. Run the following command:

mvn org.apache.maven.plugins:maven-archetype-plugin:2.4:generate -DarchetypeCatalog=https://nexus.magnolia-cms.com/content/groups/public/ 

During the execution of the command, you will be prompted to choose options or add values. Here is an overview of the parameters which you have to decide for:

ParameterValue used in this tutorialMeaning
Choose a number or apply filter

2

= An archetype to create a Magnolia project
(a parent pom and a webapp).

This creates an archetype for a Magnolia webapp.

Just enter the number. We will not apply the filter option here.

Choose archetype versionAlways choose the latest (e.g. 1.2.3-SNAPSHOT )

The version of the archetype script.

Please note that upon entering 2 in the previous step, the prompt will in fact read as follows:

Choose info.magnolia.maven.archetypes:magnolia-project-archetype version:

groupIdorg.example

The Maven groupId of this project. We use org.example .

Use a value reflecting your requirements.

artifactIDcustom-stk-project

The Maven artifact id. We use custom-stk-project .

Use a value reflecting your requirements.

version1.0-SNAPSHOT

The initial Maven version of this new project.

It is a common practice to start with 1.0-SNAPSHOT .

packageorg.example.magnolia.webapp.stk

The package name for the Java package which will be created.

Use a value reflecting your requirements.

magnolia-version

5.6.5

The Magnolia version.

We recommend using the latest version. If you rely on an older branch, you may have to adapt the version of the STK modules added.

project-namecustom-stk-project

The name of the Magnolia module.

We recommend using the same name as in the groupId parameter.

The command will summarize all the relevant parameters you have entered. To confirm the values press Y . The command will then create the following structure:

custom-stk-project/
├── custom-stk-project-webapp/
│   ├── pom.xml
│   └── src/
└── pom.xml

(The stk-example-project/stk-example-project-webapp/src folder contains more files than shown above, but you may ignore them in the context of the present topic.)

Now it's time to have a look at the two pom files. You will edit them both in the next step. (info) In the following file, study especially the dependencyManagement/dependencies section, which specifies modules versions.

custom-stk-project/pom.xml
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>org.example</groupId>
  <artifactId>custom-stk-project</artifactId>
  <name>custom-stk-project (parent pom)</name>
  <version>1.0-SNAPSHOT</version>
  <packaging>pom</packaging>

  <properties>
    <magnoliaVersion>5.6</magnoliaVersion>
    <javaVersion>1.8</javaVersion>
  </properties>

  <!-- Fill the following in, so you can use the release plugin -->
  <scm>
    <connection/>
    <developerConnection/>
    <url/>
  </scm>

  <dependencyManagement>
    <dependencies>

      <!-- Option A -->
      <!-- Importing dependencyManagement of CE bundle. -->
      <dependency>
        <groupId>info.magnolia.bundle</groupId>
        <artifactId>magnolia-bundle-parent</artifactId>
        <version>${magnoliaVersion}</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>

      <!-- Option B -->
      <!-- If you want to use the Enterprise Edition. -->
      <!--
      <dependency>
        <groupId>info.magnolia.eebundle</groupId>
        <artifactId>magnolia-enterprise-bundle-parent</artifactId>
        <version>${magnoliaVersion}</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
      -->

      <!-- TEST -->
      <dependency>
        <groupId>junit</groupId>
        <artifactId>junit</artifactId>
        <version>4.11</version>
        <scope>test</scope>
      </dependency>
    </dependencies>
  </dependencyManagement>


  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>2.3.2</version>
        <configuration>
          <source>${javaVersion}</source>
          <target>${javaVersion}</target>
        </configuration>
      </plugin>
    </plugins>

    <!-- default resources configuration which will filter your module descriptors -->
    <resources>
      <resource>
        <directory>src/main/resources</directory>
        <includes>
          <include>**/*</include>
        </includes>
      </resource>
      <resource>
        <filtering>true</filtering>
        <directory>src/main/resources</directory>
        <includes>
          <include>META-INF/magnolia/*</include>
        </includes>
      </resource>
    </resources>
  </build>

  <repositories>
    <repository>
      <id>magnolia.public</id>
      <url>https://nexus.magnolia-cms.com/content/groups/public</url>
      <snapshots>
        <enabled>true</enabled>
      </snapshots>
    </repository>
    <!-- IF YOU NEED MODULES FROM THE ENTERPRISE VERSION, UNCOMMENT THE FOLLOWING REPOSITORY -->
    <!--
    <repository>
      <id>magnolia.enterprise.releases</id>
      <url>https://nexus.magnolia-cms.com/content/repositories/magnolia.enterprise.releases</url>
      <snapshots>
        <enabled>false</enabled>
      </snapshots>
    </repository>
    -->
    <repository>
      <id>vaadin-addons</id>
      <url>https://maven.vaadin.com/vaadin-addons</url>
    </repository>
  </repositories> 
  <modules>
    <module>custom-stk-project-webapp</module>
  </modules>
</project>
(info) In the following file, study especially the dependencies section. It specifies which modules will form part of the webapp.
custom-stk-project/custom-stk-project-webapp/pom.xml
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <parent>
    <groupId>org.example</groupId>
    <artifactId>custom-stk-project</artifactId>
    <version>1.0-SNAPSHOT</version>
    <relativePath>../pom.xml</relativePath>
  </parent>
  <artifactId>custom-stk-project-webapp</artifactId>
  <name>custom-stk-project: webapp</name>
  <packaging>war</packaging>
  <dependencies>
    <!--
     Add your project specific dependencies here:
     A custom webapp typically is based on a magnolia webapp. The most simple and reduced bundle to start with is the "magnolia-empty-webapp" (see "option i" below).
     To see a complete list of preconfigured Magnolia webapps, have a look at https://documentation.magnolia-cms.com/display/DOCS56/Bundles+and+webapps
     => Please just use one of the four below listed options!
     Make sure to use the appropriate option (A or B) in the parent pom
    -->

    <!-- option i - magnolia-empty-webapp -->
    <!-- Dependencies versions are already imported by parent pom. Requires "Option A" in the parent pom. -->
    <dependency>
      <groupId>info.magnolia</groupId>
      <artifactId>magnolia-empty-webapp</artifactId>
      <type>pom</type>
    </dependency>
    <dependency>
      <groupId>info.magnolia</groupId>
      <artifactId>magnolia-empty-webapp</artifactId>
      <type>war</type>
    </dependency>


    <!-- option ii - magnolia-community-webapp -->
    <!-- Dependencies versions are already imported by parent pom. Requires "Option A" in the parent pom. -->
    <!--
    <dependency>
      <groupId>info.magnolia.bundle</groupId>
      <artifactId>magnolia-community-webapp</artifactId>
      <type>pom</type>
    </dependency>
    <dependency>
      <groupId>info.magnolia.bundle</groupId>
      <artifactId>magnolia-community-webapp</artifactId>
      <type>war</type>
    </dependency>
    -->


    <!-- option iii - magnolia-enterprise-standard-webapp -->
    <!-- Dependencies versions are already imported by parent pom. Requires "Option B" in the parent pom. -->
    <!--
    <dependency>
      <groupId>info.magnolia.eebundle</groupId>
      <artifactId>magnolia-enterprise-standard-webapp</artifactId>
      <type>pom</type>
    </dependency>
    <dependency>
      <groupId>info.magnolia.eebundle</groupId>
      <artifactId>magnolia-enterprise-standard-webapp</artifactId>
      <type>war</type>
    </dependency>
    -->


    <!-- option iv - magnolia-enterprise-pro-webapp -->
    <!-- Dependencies versions are already imported by parent pom. Requires "Option B" in the parent pom. -->
    <!--
    <dependency>
      <groupId>info.magnolia.eebundle</groupId>
      <artifactId>magnolia-enterprise-pro-webapp</artifactId>
      <type>pom</type>
    </dependency>
    <dependency>
      <groupId>info.magnolia.eebundle</groupId>
      <artifactId>magnolia-enterprise-pro-webapp</artifactId>
      <type>war</type>
    </dependency>
    -->

  </dependencies>

  <build>
    <plugins>
      <plugin>
        <artifactId>maven-war-plugin</artifactId>
        <configuration>
          <!-- exclude jars copied "physically" from the webapp overlay - so we only get those resolved by Maven's dependency management -->
          <dependentWarExcludes>WEB-INF/lib/*.jar</dependentWarExcludes>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>


Step 2: Overlaying magnolia-enterprise-pro-webapp

In this step you will make sure that your webapp inherits from the magnolia-enterprise-pro-webapp . Maven will create the so-called Overlay. You must adapt both the version management section and and the module management sections. You have to edit both pom files shown above.

Adapting the version management section

In custom-stk-project/pom.xml edit the dependencyManagement/dependencies section. Delete the section marked as "Option A" and uncomment "Option B". Keep the block marked as "TEST". When done, the dependency management section should look like this:

custom-stk-project/pom.xml (snippet)
  <dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>info.magnolia.eebundle</groupId>
        <artifactId>magnolia-enterprise-bundle-parent</artifactId>
        <version>${magnoliaVersion}</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
      <!-- TEST -->
      <dependency>
        <groupId>junit</groupId>
        <artifactId>junit</artifactId>
        <version>4.11</version>
        <scope>test</scope>
      </dependency>
    </dependencies>
  </dependencyManagement>
The pom imports the version management section of magnolia-enterprise-bundle-parent (and it manages the version for junit). In step 3 you will also specify the version of the STK modules in the section.

Adapting the module management section

In custom-stk-project/custom-stk-project-webapp/pom.xml edit the dependencies section. Uncomment the section marked as "option iv", delete the options i, ii and iii. The dependencies section should then look as follows:

custom-stk-project/custom-stk-project-webapp/pom.xml (snippet)
  <dependencies>
    <dependency>
      <groupId>info.magnolia.eebundle</groupId>
      <artifactId>magnolia-enterprise-pro-webapp</artifactId>
      <type>pom</type>
    </dependency>
    <dependency>
      <groupId>info.magnolia.eebundle</groupId>
      <artifactId>magnolia-enterprise-pro-webapp</artifactId>
      <type>war</type>
    </dependency>
  </dependencies>
These dependencies will instruct Maven to merge the artifacts from magnolia-enterprise-pro-webapp into the project. In step 3 you will add the STK modules to the webapp.

Step 3: Adding the STK modules

Here are the modules which you have to add to enable the standard templating kit:

magnolia-module-standard-templating-kitThe module which contains the templates.Required
magnolia-theme-popA theme.Required when using the demo project, see the next row.
magnolia-demo-projectA demo project based on the STK templates and the pop theme.Optional

Be aware that the above modules have transient dependendencies to other Magnolia modules, for example to magnolia-module-public-user-registration and magnolia-module-device-detection . These dependencies are handled by Maven automatically. Now let's edit the pom files again. 

Editing custom-stk-project/pom.xml

Add the following snippet to the dependencyManagement/dependencies section:

      <!-- stk modules versions -->
      <dependency>
        <groupId>info.magnolia</groupId>
        <artifactId>magnolia-module-standard-templating-kit</artifactId>
        <version>${stkVersion}</version>
      </dependency>
      <dependency>
        <groupId>info.magnolia</groupId>
        <artifactId>magnolia-theme-pop</artifactId>
        <version>${stkVersion}</version>
      </dependency>
      <dependency>
        <groupId>info.magnolia</groupId>
        <artifactId>magnolia-demo-project</artifactId>
        <version>${stkVersion}</version>
      </dependency>
      <!-- TEST -->

Please note that the version tags of the added dependencies do not contain the value but a variable instead. Set this variable in the properties section at the beginning of the file.

For a Magnolia 5.6 webapp use the latest minor version of the STK 3.1.x series which is  3.1.1 .

 Click here to see the complete file

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>org.example</groupId>
  <artifactId>custom-stk-project</artifactId>
  <name>custom-stk-project (parent pom)</name>
  <version>1.0-SNAPSHOT</version>
  <packaging>pom</packaging>

  <properties>
    <magnoliaVersion>5.6</magnoliaVersion>
    <javaVersion>1.8</javaVersion>
    <stkVersion>3.1</stkVersion>
  </properties>

  <dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>info.magnolia.eebundle</groupId>
        <artifactId>magnolia-enterprise-bundle-parent</artifactId>
        <version>${magnoliaVersion}</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
      <!-- stk modules versions -->
      <dependency>
        <groupId>info.magnolia</groupId>
        <artifactId>magnolia-module-standard-templating-kit</artifactId>
        <version>${stkVersion}</version>
      </dependency>
      <dependency>
        <groupId>info.magnolia</groupId>
        <artifactId>magnolia-theme-pop</artifactId>
        <version>${stkVersion}</version>
      </dependency>
      <dependency>
        <groupId>info.magnolia</groupId>
        <artifactId>magnolia-demo-project</artifactId>
        <version>${stkVersion}</version>
      </dependency>
      <!-- TEST -->
      <dependency>
        <groupId>junit</groupId>
        <artifactId>junit</artifactId>
        <version>4.11</version>
        <scope>test</scope>
      </dependency>
    </dependencies>
  </dependencyManagement>


  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>2.3.2</version>
        <configuration>
          <source>${javaVersion}</source>
          <target>${javaVersion}</target>
        </configuration>
      </plugin>
    </plugins>

    <!-- default resources configuration which will filter your module descriptors -->
    <resources>
      <resource>
        <directory>src/main/resources</directory>
        <includes>
          <include>**/*</include>
        </includes>
      </resource>
      <resource>
        <filtering>true</filtering>
        <directory>src/main/resources</directory>
        <includes>
          <include>META-INF/magnolia/*</include>
        </includes>
      </resource>
    </resources>
  </build>

  <repositories>
    <repository>
      <id>vaadin-addons</id>
      <url>https://maven.vaadin.com/vaadin-addons</url>
    </repository>
  </repositories>

  <modules>
    <module>custom-stk-project-webapp</module>
  </modules>
</project>

Editing custom-stk-project/custom-stk-project-webapp/pom.xml

Add the following snippet to the dependencies section:

    <!-- required modules to use STK -->
    <dependency>
      <groupId>info.magnolia</groupId>
      <artifactId>magnolia-module-standard-templating-kit</artifactId>
    </dependency>
    <dependency>
      <groupId>info.magnolia</groupId>
      <artifactId>magnolia-theme-pop</artifactId>
    </dependency>
    <dependency>
      <groupId>info.magnolia</groupId>
      <artifactId>magnolia-demo-project</artifactId>
    </dependency>
    <!-- EOF: stk modules section -->

 Click here to see the complete file

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <parent>
    <groupId>org.example</groupId>
    <artifactId>custom-stk-project</artifactId>
    <version>1.0-SNAPSHOT</version>
    <relativePath>../pom.xml</relativePath>
  </parent>
  <artifactId>custom-stk-project-webapp</artifactId>
  <name>custom-stk-project: webapp</name>
  <packaging>war</packaging>

  <dependencies>
    <dependency>
      <groupId>info.magnolia.eebundle</groupId>
      <artifactId>magnolia-enterprise-pro-webapp</artifactId>
      <type>pom</type>
    </dependency>
    <dependency>
      <groupId>info.magnolia.eebundle</groupId>
      <artifactId>magnolia-enterprise-pro-webapp</artifactId>
      <type>war</type>
    </dependency>
    <!-- required modules to use STK -->
    <dependency>
      <groupId>info.magnolia</groupId>
      <artifactId>magnolia-module-standard-templating-kit</artifactId>
    </dependency>
    <dependency>
      <groupId>info.magnolia</groupId>
      <artifactId>magnolia-theme-pop</artifactId>
    </dependency>
    <dependency>
      <groupId>info.magnolia</groupId>
      <artifactId>magnolia-demo-project</artifactId>
    </dependency>
    <!-- EOF: stk modules section -->
  </dependencies>

  <build>
    <plugins>
      <plugin>
        <artifactId>maven-war-plugin</artifactId>
        <configuration>
          <!-- exclude jars copied "physically" from the webapp overlay - so we only get those resolved by Maven's dependency management -->
          <dependentWarExcludes>WEB-INF/lib/*.jar</dependentWarExcludes>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>

Step 4: Setting the pro widgetset

Since you are creating a webapp based on the EE pro webapp, you have to make sure that the webapp is configured to use the pro widgetset (see Magnolia widgetsets).

Go to the custom-stk-project-webapp/src/main/webapp/WEB-INF/config/default folder or create the folder if it doesn't exist yet. Create the magnolia.properties file there:

magnolia.properties
#--------------------------------------------
# Enterprise Pro webapp properties, currently only difference is Pro Widgetset.
#
# Here we define some properties not
# configured in the config repository.
# They are used in common before the initialization
# of the repositories.
#
# WARNING: on Windows systems, either use the /
# to separate path elements, or escape the \ with
# another \, i.e C:\\magnolia\\data\\repositories
# or c:/magnolia/data/repositories
#--------------------------------------------
magnolia.home=${magnolia.app.rootdir}
# The directory to expose file system resources from
magnolia.resources.dir=${magnolia.home}/modules
# Pattern to define which resources should be observed by ClasspathScanner
magnolia.resources.classpath.observation.pattern=.*\\.(ftl|yaml)$
# Directories relative to magnolia.resources.dir which will be excluded from FileResourceOrigin observation.
# Also see info.magnolia.resourceloader.file.FileSystemResourceOrigin#EXCLUDED_DIRECTORIES
#magnolia.resources.filesystem.observation.excludedDirectories=META-INF,WEB-INF,cache,docroot,logs,repositories,tmp
magnolia.cache.startdir=${magnolia.home}/cache
magnolia.upload.tmpdir=${magnolia.home}/tmp
magnolia.exchange.history=${magnolia.home}/history
magnolia.repositories.config=WEB-INF/config/default/repositories.xml
magnolia.repositories.home=${magnolia.home}/repositories
magnolia.repositories.jackrabbit.config=WEB-INF/config/repo-conf/jackrabbit-bundle-h2-search.xml

log4j.config=WEB-INF/config/default/log4j2.xml
magnolia.logs.dir=${magnolia.home}/logs

# The directories in which the bootstrap files are searched
magnolia.bootstrap.dir=WEB-INF/bootstrap/author WEB-INF/bootstrap/common

# This is only used for the initial installation afterward the configuration in the config repository is used
# The value is saved in /server/admin
magnolia.bootstrap.authorInstance=true

# Some modules contain optional sample content. They will check this property to decide if they should install
# the sample data
magnolia.bootstrap.samples=true

# Activate UTF-8 support to pages
magnolia.utf8.enabled=false

# Switch to false to enhance the performance of the javascript generation and similar
magnolia.develop=false

# Change to point at your custom Vaadin widgetset and theme
# Your widgetset should always inherit magnolia's Pro widgetset (info.magnolia.widgetset.MagnoliaProWidgetSet)
magnolia.ui.vaadin.widgetset=info.magnolia.widgetset.MagnoliaProWidgetSet
# Your theme should always include magnolia's default theme (admincentral)
magnolia.ui.vaadin.theme=admincentral

# Contact details displayed in the footer of the login form
#magnolia.service.contact=

#--------------------------------------------
# Repository connection
#--------------------------------------------
magnolia.connection.jcr.userId = admin
magnolia.connection.jcr.password = admin

# Set it to true if bootstrapping/update should be performed automatically
magnolia.update.auto=false

# 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.author.key.location=${magnolia.home}/WEB-INF/config/default/magnolia-activation-keypair.properties

Step 5: Building the webapp with Maven

Now you are ready to build the webapp with Maven. Open a shell, go to the custom-stk-project/custom-stk-project-webapp/ directory and execute:

mvn clean install
Alternatively, go to the custom-stk-project/ directory and execute:
mvn clean install -am -pl custom-stk-project-webapp
Either way should result in:
[INFO] BUILD SUCCESS
Congratulations! Your webapp is finished. (smile) You can start it from your IDE for further development.

For a production environment consider using a different persistence layer instead of the embedded H2. When deploying the webapp as WAR you should at least change the path to the repository. You can also add another module to your project to create an artifact which bundles Tomcat or another servlet container with your webapp.

Adapting a webapp manually

This section explains how you can adapt a webapp by adding (and removing) JAR files to make sure it contains the STK modules. The aim is, again, to end up with an enterprise PRO webapp with the STK modules.

Compared to Maven-based solutions, adjusting a webapp manually is more error-prone and also harder to maintain.

The base artifact: magnolia-enterprise-pro-demo-bundle

Start with a preconfigured artifact provided by Magnolia. This time take a complete bundle which comes together with Tomcat. Tomcat bundles are first-choice artifacts for quick testing scenarios or for users who do not want to invest in custom Maven setups.

Download  magnolia-enterprise-pro-demo-bundle-5.6.5-tomcat-bundle.zip , copy it to a folder of your choice, unzip it, but do not start the bundle yet.


Adapting webapps/magnoliaAuthor/WEB-INF/lib

Open the magnolia-enterprise-<x.y>/apache-tomcat-8.5.5/webapps/magnoliaAuthor/WEB-INF/lib folder. It contains the JAR files whose content you will adapt. Note that the webapps folder – at this moment, before the bundle has been started for the first time – contains only one complete webapp: magnoliaAuthor. During the first start, the start script will copy the WEB-INF folder to the magnoliaPublic folder. That's why both webapps will contain the same modules (and JAR files).

Be aware of transient dependencies

Magnolia modules often have dependencies to other Magnolia modules or to modules provided by third-party providers. When manually tailoring a webapp, you have to make sure that the library files for the dependent modules are also provided.

Removing travel-demo's JAR files

Since we start with magnolia-enterprise-pro-demo-bundle , we have to get rid of the Magnolia travel demo modules. The bundle cannot contain both demo projects. Therefore, remove the following JAR files from the webapps/magnoliaAuthor/WEB-INF/lib folder (all JAR files beginning with magnolia-travel* ):

  • magnolia-travel-demo-x.y-.jar
  • magnolia-travel-demo-component-personalization-x.y-.jar
  • magnolia-travel-demo-content-tags-x.y-.jar
  • magnolia-travel-demo-marketing-tags-x.y-.jar
  • magnolia-travel-demo-multisite-x.y-.jar
  • magnolia-travel-demo-personalization-x.y-.jar
  • magnolia-travel-demo-stories-app-x.y-.jar

  • magnolia-travel-tours-x.y.jar

( x.y is a placeholder for real version numbers.)

Adding STK module's JAR files

Now add the following JAR files to the webapps/magnoliaAuthor/WEB-INF/lib folder:

Starting the bundle

Now the bundle is ready to be started the first time.

With CLI

Go to the parent directory of the apache-tomcat directory and execute the Magnolia CLI start command:

mgnl start

When starting for the first time, Magnolia runs a web update and automatically installs all its modules.

Without CLI

Go to the magnolia-x.y/apache-tomcat-x.y/bin directory and type:

./magnolia_control.sh start

Note: In case you get an error due to a low "max open files" limit, you may try executing the command with
the --ignore-open-files-limit option:

./magnolia_control.sh start --ignore-open-files-limit

Detailed instructions:

 Mac OS X
  1. Open a terminal window in Applications > Utilities > Terminal.
  2. Go to the Magnolia installation directory

    cd /Applications/magnolia-x.y/apache-tomcat/bin
  3. Start Magnolia.

    ./magnolia_control.sh start && tail -f ../logs/catalina.out

The first part of the startup command ./magnolia_control.sh start launches Magnolia. The second part && tail -f ../logs/catalina.out displays log messages written to /apache-tomcat/logs/catalina.out log file. This makes it easier to troubleshoot startup errors.

Magnolia reports startup information. If startup fails, look for the reason in the report. In a successful startup the last line reads: 
INFO: Server startup in 12345 ms.

To stop Magnolia, type CTRL + C, then ./magnolia_control.sh stop and press RETURN.

 Windows
  1. Open a command prompt and go to the Magnolia installation directory. 
    (To do this, type cd C:\Users\<username>\magnolia-x.y\apache-tomcat\bin)
  2. Type magnolia_control.bat start and press ENTER.
    Magnolia reports startup information in a new Tomcat window. If startup fails, look for the reason in the report. In a successful startup the last line reads: INFO: Server startup in 12345 ms

To stop Magnolia, type CTRL + C , then ./magnolia_control.bat stop and press ENTER.

 Linux
  1. Open a terminal window.
  2. Go to the Magnolia installation directory: 
    cd /home/<your account>/magnolia-x.y/apache-tomcat/bin 
    Your path may be different.
  3. Start Magnolia: 
    In bash shell: ./magnolia_control.sh start && tail -f ../logs/catalina.out
    In fish shell: ./magnolia_control.sh start; tail -f ../logs/catalina.out

The first part of the startup command ./magnolia_control.sh start launches Magnolia. The appended part tail -f ../logs/catalina.out displays log messages written to /apache-tomcat/logs/catalina.out log file. This makes it easier to troubleshoot startup errors.

Magnolia reports startup information. If startup fails, look for the reason in the report. In a successful startup the last line reads: 
INFO: Server startup in 12345 ms

To stop Magnolia, type CTRL + C , then ./magnolia_control.sh stop and press ENTER.

 Solaris
  1. Open a terminal window.
  2. Go to the Magnolia installation directory: 
    cd /home/userAccount/magnolia-x.y/apache-tomcat/bin 
    Your path may be different.
  3. Start Magnolia: 
    ./magnolia_control.sh start && tail -f ../logs/catalina.out

The first part of the startup command ./magnolia_control.sh start launches Magnolia. The second part && tail -f ../logs/catalina.out displays log messages written to /apache-tomcat/logs/catalina.out log file. This makes it easier to troubleshoot startup errors.

Magnolia reports startup information. If startup fails, look for the reason in the report. In a successful startup the last line reads: 
INFO: Server startup in 12345 ms

To stop Magnolia, type CTRL + C , then ./magnolia_control.sh stop and press ENTER.


  • No labels