This is an updated version of a how-to written for Intrepid (8.10), now horrendously out-of-date. It was written for Maverick (10.10) but should also work on Lucid (10.04).

No knowledge of Ubuntu or Linux is assumed; the intended audience is someone who's managed to install Ubuntu and isn't too intimidated by the Terminal. (Hint: You can copy and paste, but in Terminal, pasting is Ctrl + Shift +C)

Step 1: Installing Java SDK

(Thanks to Daniel Bruegge for the tip)

  • Open the Terminal (Applications > Accessories > Terminal)
  • On Maverick: type:
    sudo add-apt-repository "deb http://archive.canonical.com/ maverick partner"
  • On Lucid: type:
    sudo add-apt-repository "deb http://archive.canonical.com/ lucid partner"
  • Type:
    sudo apt-get update

    This will check all the software repositories for what updates are available, including java.

  • Type:
    sudo apt-get install sun-java6-jdk

    It will ask you if you want to continue; type y to confirm.

  • You'll have to agree to the TOS and license (you can use the tab key to move between the options) and then it'll install on its own.

Step 2: Installing Maven

  • Open Terminal, and type
    sudo apt-get install maven2

    This will list all the packages that need to be installed; type y to proceed

Step 3: Installing Cocoon

  • Open the Terminal and type
    mvn archetype:generate -DarchetypeCatalog=http://cocoon.apache.org
  • This begins the install process.
    • For archetype, choose 2
    • Define value for groupId: - This should be a unique value. A classic value to use is, if you own the namespace myurl.com, you could type com.myurl
    • Define value for artifactId: cocoon
    • Define value for version: 1.0-SNAPSHOT: 1.0.0
    • Define value for package: - groupID.cocoon (i.e. com.myurl.cocoon)
    • Confirm the properties
  • After everything's done installing, you should see [INFO] BUILD SUCCESSFUL

Cocoon will install in your Home folder, in a folder named the same thing as whatever you put for your artifactID. Here, the folder is named cocoon.

Step 4: Starting Jetty

You need to make a configuration change in the Maven settings.xml to be able to run Jetty. (Thanks to Ganesh Gembali for the tip.)

  • Open up Terminal and type
    sudo gedit /etc/maven2/settings.xml
  • This will pop up a text editor with settings.xml. Search for pluginGroups, and between
    and , add 
    org.mortbay.jetty
  • Make sure you're in your cocoon directory in Terminal (does it say ~/cocoon$ right before the cursor?), and type
    mvn jetty:run
  • There'll be a lot more installing, but it should conclude with [INFO] Started Jetty Server
  • Open a browser and go to http://localhost:8888/cocoon - you should see a message saying Apache Cocoon: Welcome

Step 5: Cocoon Add-ons

There are a couple add-ons for Cocoon that are essentials-- like generators for HTML. If you want to use XSLT 2.0, Saxon 9 is also critical. Possibly less important are the FOP processor (to generate PDFs from XSL-FO), Batik (for SVG) and Forms (to genrate forms). If you don't need to use XSLT 2.0, you can skip the first part of this section.

  • Installing Saxon 9 - a good idea
    • Open your cocoon directory and navigate to src/main/resources/META-INF/cocoon
    • Create directory avalon
    • Create the following files in Text Editor (Applications > Accessories > Text Editor), and place them in the avalon directory:
      • File named cocoon-core-xslt-saxon.xconf
      • File named sitemap-transformers-saxon-transformer.xconf
        



 
saxon
    • Download Saxon-HE 9.2 for Java. By default, this will go into your Downloads folder.
    • Extract the zip file; you can delete everything but saxon9he.jar
    • Open a new Terminal
      cd cocoon
mvn install:install-file -DgroupId=net.sf.saxon -DartifactId=saxon -Dversion=9.2.1.2 -Dpackaging=jar -Dfile=../Downloads/saxon9he.jar
    • Go to cocoon and open pom.xml
    • At the bottom of , add:
        
net.sf.saxon    
saxon    
9.2.1.2
    • If for some reason you only want Saxon 9 and not the ability to generate HTML, skip to the bottom of this section
  • Installing HTML support
    • Still in pom.xml, at the bottom of , add:
      
org.apache.cocoon

cocoon-html-impl
1.0.0
  • Installing FOP (for PDFs)
    • Still in pom.xml, at the bottom of , add:
      
org.apache.cocoon
cocoon-fop-impl
1.0.0
  • Installing Batik (SVG)
    • Still in pom.xml, at the bottom of , add:
      
org.apache.cocoon

cocoon-batik-impl
1.0.0
  • Installing Forms
    • Still in pom.xml, at the bottom of , add:
      
org.apache.cocoon
cocoon-forms-impl
1.0.0-RC1
  • There's a list of all blocks, and the syntax for the dependency code is in there someplace.
  • Once you're done adding dependencies:
    • If you have a Terminal open with [INFO] Started Jetty Server, close it.
    • Open a new Terminal
      cd cocoon
            
mvn compile
    • After it's done...
      mvn jetty:run

    • Redirecting the Sitemap

    You can add your pipelines to the sitemap.xmap in cocoon/src/main/resources/COB-INF, or (more conveniently) you can tell that base sitemap to look elsewhere for your files.

    I'm assuming here that you have a folder called myproject in your Home folder where you have all your files and your sitemap. Please change that, and your user name, accordingly.

    Included here is also the code to generate more useful error messages than a blank pages.

    In sitemap.xmap in cocoon/src/main/resources/COB-INF, at the bottom of the
    section, add:

    In this case, your project will be found at http://localhost:8888/cocoon/myproject/[things that match your pipelines]. But it doesn't have to match the folder name with your files. You can change the URL by chanigng to

    Hints and Tips

    Every time you restart Ubuntu, you have to restart Cocoon:

    cd cocoon
mvn jetty:run

    Be sure to keep that Terminal window open while you're working with Cocoon. You can always check if Cocoon is working by going to: http://localhost:8888/cocoon.

    This guide was prepared with help from a guide written on the GSLIS wiki by Wendell Piez. If you try it and something doesn't work, please post a comment. This document is licensed Creative Commons Attribution.