Setting Up Cocoon 2.2

THL Toolbox > Developers' Zone > Web Development > Setting Up Cocoon 2.2

Setting Up Cocoon 2.2 as a Tomcat Servlet

Contributor(s): Than Grove

To transform XML content into web pages, THL uses Apache Cocoon as a servlet within Tomcat. Initially, we used Cocoon 2.1.11 built into a servlet by members of the UVa library staff. In April of 2012, it was decided we should begin the migration to Cocoon 2.2, which represents a major shift in architecture and deployment. Cocoon 2.2 is fully modular, its functionality having been segregated into blocks. Furthermore, the Apache Maven program is used, instead of Ant, to build a project from Cocoon. Once the Cocoon WAR file has been built, it is easy to install but the building of the .war file is more complicated issue. To document this process, the steps taken to create the cocoon22.war file presently installed on THL's Development are detailed below.

Creating the Cocoon 2.2 War file

  1. Installed Maven 3.0.4
    • Downloaded Maven and unpacked it to /etc/maven-3.0.4
    • Set your shell path to recognize Maven by doing:
      • [sds-deployer@dev1 cocoonCore?]$ export M2_HOME=/etc/maven-3.0.4/
      • [sds-deployer@dev1 cocoonCore?]$ export M2=$M2_HOME/bin
      • [sds-deployer@dev1 cocoonCore?]$ export PATH=$M2:$PATH
    • Check to make sure it is installed by entering "mvn --version"
  2. At /usr/local/projects/thlib-cocoon/cocoon22/ executed the command "mvn archetype:generate -DarchetypeCatalog=http://cocoon.apache.org"
  3. After downloading many files, it asks to choose one of three options. Chose 2 "Create a cocoon block containing some small samples" and set the following parameters:
    • Group ID: org.thlib
    • Artifact ID: cocoonCore (or cocoonBlock)
    • Version: 1.0.0
    • Package: org.thlib.cocoonCore (or org.thlib.cocoonBlock)
  4. Edit the file cocoonCore/pom.xml by running "vi pom.xml" and make the following changes:
    • Add the dependency for FOP at the end of the group of <dependencies>. This code is below in Code Snipets > Dependencies > FOP
    • change the line "<Cocoon-Block-Name>${pom.artifactId}</Cocoon-Block-Name>" to "<Cocoon-Block-Name>${project.artifactId}</Cocoon-Block-Name>"
    • Save with :x
  5. Within the block code navigate to and edit the sitemap.xmp in vi: {block folder}/src/main/resources/COB-INF/sitemap.xmap
    • Remove demo pipeline code at top of the Pipelines element.
    • Under the Pipelines element at the top add the Pipeline code to read and use sub-directory sitemaps from the pipeline section below.
    • Save file with :x
  6. Navigate back to home folder /usr/local/projects/thlib-cocoon/cocoon22 and run the command again: "mvn archetype:generate -DarchetypeCatalog=http://cocoon.apache.org" but pick option 3 and enter the following params entered upon request:
    • Group ID: org.thlib
    • Artifact ID: cocoonWebapp
    • Version: 1.0.0
    • Package: org.thlib.cocoonWebapp
  7. Edit the file cocoonWebapp/pom.xml with vi and make the following changes:
    • Comment out the Jetty <plugin> definition
    • Add the plugin definition for either Tomcat 6 or 7, depending on which you are using. See below in Code Snippets > Plugin Definitions.
    • Add a dependency to the org.thlib.cocoonCore block by adding the code found in This code is below in Code Snipets > Dependencies > Cocoon Core.
    • Save the file with :x
  8. Configure for use in THL Projects folder:
    • cd /usr/local/projects/thlib-cocoon/cocoon22/cocoonCore/src/main/resources/META-INF/cocoon/spring/
    • vi block-servlet-service.xml
    • Change the line for <servlet:context …> to "<servlet:context mount-path="" context-path="file:///usr/local/projects/thlib-texts/current/cocoon/"/>"
      • This means that the path to invoke cocoon (mount-path) would be whatever is declared in Context Path when deployed in Context (in this case /cocoon or the full url of external link: http://dev.thlib.org:8080/cocoon) and the root for the application (context-path) is the location of the THL XML Texts SVN repository on Dev1.
  9. Change folder to /thlib-cocoon/cocoon22/cocoonCore/
  10. Run "mvn install"
  11. Change back to /thlib-cocoon/cocoon22/cocoonWebapp/
  12. Run "mvn package"
  13. cp cocoonWebapp-1.0.0.war to /thlib-cocoon/cocoon22/shared/

Adding Tomcat Manager To Tomcat6 Install

On Dev1 thlib.org, Tomcat manager was not installed. So, I installed that by:

  1. Logging onto Dev1 with secureCRT
  2. sudo su root (my password)
  3. cd /usr/share/tomcat (though not necessary I think)
  4. Run "sudo yum install tomcat6-admin-webapps"
  5. cd /etc/tomcat6 and vi tomcat-users.xml, added manager-gui role and "deployer" user with the same password as on previous dev.
  6. Restarted tomcat by doing "systemctl stop tomcat6.service" and "systemctl start tomcat6.service" as I wasn't sure if "systemctl restart tomcat6.service" was working right.
  7. Then I could logon to manager.

Test Of Cocoon Webapp

Tried installing webapp using the manager to see if demo would work before configuring for THL:

  1. Placed war from cocoon22/cocoonWebapp/target in /usr/local/projects/thlib-cocoon/current and created the Tomcal web app context file at /usr/local/projects/thlib-cocoon/shared/thlib-cocoon.xml
  2. Went to external link: http://dev.thlib.org:8080/manager/html
  3. At the bottom of the list entered:
    • Context Path: /cocoon
    • XML Configuration file URL: /usr/local/projects/thlib-cocoon/current/cocoonWebapp-1.0.0.war
  4. And pressed deploy button but it was not working. Apparently there is a bug (see external link: http://www.coderanch.com/t/524388/Tomcat/Tomcat-cannot-deploy-application-access and external link: https://issues.apache.org/bugzilla/show_bug.cgi?id=51147) You have to edit the html page in browser (in Chrome using ctrl+shift+I and change the form method from "get" to "post").

Increasing Memory for Tomcat

Turns out the memory setting for Tomcat was not boosted like it is on old Dev, Staging and Production. So edited the /etc/tomcat6/tomcat6.conf file with vi and added CATALINA_OPTS variable in the following context:

CATALINA_TMPDIR="/var/cache/tomcat6/temp"
CATALINA_OPTS="-server -Xmx3000m -Xms3000m -XX:+UseParallelGC -XX:+AggressiveOpts -XX:PermSize=256m -XX:MaxPermSize=512m -Djava.awt.headless=true"

Then restarted Tomcat

Configuration for Site

Test worked but need to make certain modifications to get it to work in THL.

  1. cd /usr/local/projects/thlib-cocoon/cocoon22/cocoonCore/src/main/resources/META-INF/cocoon/spring/
  2. vi block-servlet-service.xml
  3. Change the line for <servlet:context …> to "<servlet:context mount-path="" context-path="file:///usr/local/projects/thlib-texts/current/cocoon/"/>"
    • This means that the path to invoke cocoon (mount-path) would be whatever is declared in Context Path when deployed in Context (in this case /cocoon or the full url of external link: http://dev.thlib.org:8080/cocoon) and the root for the application (context-path) is the location of the THL XML Texts SVN repository on Dev1.
  4. cd /usr/local/projects/thlib-cocoon/cocoon22/cocoonCore/
  5. Run "mvn install"
  6. cd /usr/local/projects/thlib-cocoon/cocoon22/cocoonWebapp/
  7. Run "mvn package"
  8. Install as above.

Potential Need for Redirect

When this was done for the new production (sdsv11), the URL used to access a cocoon site was ../cocoon/texts but the subfolders (jiats, essays, catalogs, etc.) were all in /usr/local/projects/thlib-texts/current/cocoon/. I thus needed to create a symlink *within* the cocoon folder that was called "texts" but pointed to the cocoon folder so that the url /usr/local/projects/thlib-texts/current/cocoon/texts/ would point to the cocoon folder. Thus within the cocoon folder when you "ls" it, you have the following entry:

lrwxrwxrwx  1 sds-deployer rpcuser    47 Apr  7 07:25 texts -> /usr/local/projects/thlib-texts/current/cocoon/

Code Snippets

Dependencies

Upgrade Spring Framework

Add the following code to your pom.xml dependencies:

<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-aop</artifactId>
    <version>3.2.5.RELEASE</version>
</dependency>

FOP

<!-- Added Dependecies -->
    <!-- FOP (Added by ndg8f, 2012-05-02 -->
    <dependency>
      <groupId>org.apache.cocoon</groupId>
      <artifactId>cocoon-fop-impl</artifactId>
      <version>1.0.0</version>
    </dependency>

Cocoon Core

<dependencies>
    <dependency>
      <groupId>org.thlib</groupId>
      <artifactId>cocoonCore</artifactId>
      <version>1.0.0</version>
    </dependency>
  </dependencies>

Plugin Definitions

<plugin>
  <groupId>org.apache.tomcat.maven</groupId>
  <artifactId>tomcat6-maven-plugin</artifactId>
  <version>2.3-SNAPSHOT</version>
</plugin>

or 

<plugin>
  <groupId>org.apache.tomcat.maven</groupId>
  <artifactId>tomcat7-maven-plugin</artifactId>
  <version>2.0-SNAPSHOT</version>
</plugin>

Pipeline Code

<!-- Mount everything  by calling the sitemap.xmap file located. This will be cocoon/texts on tomcat -->
    <map:match pattern="*/**">
      <map:mount check-reload="${sitemap-mount.check-reload}" src="{1}/" uri-prefix="{1}"/>
    </map:match>

Provided for unrestricted use by the external link: Tibetan and Himalayan Library