10/11/10 -- This guide was written for Intrepid, and doesn't work on the latest Ubuntu releases. An updated and working version of the guide is available here.
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 e-mail me (quinnd -at- uchicago +dot+ edu). This document is licensed Creative Commons Attribution.
No knowledge of Ubuntu or Unix is assumed; the intended audience is someone who's managed to install Ubuntu and isn't too intimidated by the Terminal.

Step 1: Installing Java SDK

  1. Open the Terminal (Applications > Accessories > Terminal)
  2. Type: sudo apt-get install sun-java6-jdk
    (Hint: You can copy and paste, but in Terminal, pasting is Ctrl + Shift +C)
  3. There'll be some downloading, you'll have to scroll through a long TOS and agree to it, but then it will install on its own.
  4. Close Terminal.

Step 2: Installing Maven
Derived from Maven in Five Minutes.

  1. Download Maven (choose tar.bz2)
  2. Open the tar.bz file; by default, it probably saved to the Desktop
  3. Extract it to the Desktop
  4. Open the Terminal again and type: cd /usr/local

    sudo mkdir apache-mavenAt this point, the Terminal will ask you for your sudo password. It's the same as the password you use to log in to Ubuntu. Then:
    cd /home/YOUR_USER_NAME/Desktop (be sure to replace YOUR_USER_NAME with your user name)

    sudo mv apache-maven-2.0.9 /usr/local/apache-maven

    export M2_HOME=/usr/local/apache-maven/apache-maven-2.0.9

    export PATH=$M2:$PATH

  5. Cross you fingers and type:
    mvn --version
  6. If everything worked right, it should display information about the version of Maven you have installed.
  7. Close Terminal.

Step 3: Installing Cocoon

Derived from Your first Cocoon application.

  1. Make a directory for your Cocoon install.
    • Using the GUI: go to Places > Home Folder, then in that new window, File > Create Folder.
    • Or, open the Terminal:mkdir cocoon
    • In the following text, I'm assuming you make a folder called cocoon in your Home Folder; if you give it a different name or put it somewhere else, you'll have to change the commands accordingly.
  2. Open the Terminal and change directory to your cocoon folder:cd cocoon

    mvn archetype:generate -DarchetypeCatalog=http://cocoon.apache.org

  3. 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)
  4. After everything's done installing, you should see [INFO] BUILD SUCCESSFUL
  5. Make sure you're in your cocoon directory in Terminal (does it say ~/cocoon$ right before the cursor?), and type mvn jetty:run
  6. There'll be a lot more installing, but it should conclude with [INFO] Started Jetty Server
  7. Open a browser and go to http://localhost:8888/cocoonTest - you should see a message saying Apache Cocoon: Welcome

Step 4: 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, Saoxn 9 is also critical. Posibly 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.

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


        class="org.apache.cocoon.components.xslt.TraxProcessor">


      2. File named sitemap-transformers-saxon-transformer.xconf




        saxon

    4. Download http://prdownloads.sourceforge.net/saxon/saxonb9-1-0-5j.zip
    5. Extract the zip file to you Home folder; you can delete everything but saxon9.jar
    6. Open a new Terminalcd cocoon

      mvn install:install-file -DgroupId=net.sf.saxon -DartifactId=saxon -Dversion=9.1.0.5 -Dpackaging=jar -Dfile=../saxon9.jar

    7. Go to cocoon and open pom.xml
    8. At the bottom of , add:


      net.sf.saxon
      saxon
      9.1.0.5

    9. If for some reason you only want Saxon 9 and not the ability to generate HTML, skip to the bottom of this section
  2. Installing HTML support
    • Still in pom.xml, at the bottom of , add:


      org.apache.cocoon

      cocoon-html-impl
      1.0.0

  3. Installing FOP (for PDFs)
    • Still in pom.xml, at the bottom of , add:


      org.apache.cocoon
      cocoon-fop-impl
      1.0.0

  4. Installing Batik (SVG)
    • Still in pom.xml, at the bottom of , add:


      org.apache.cocoon

      cocoon-batik-impl
      1.0.0

  5. Installing Forms
    • Still in pom.xml, at the bottom of , add:


      org.apache.cocoon
      cocoon-forms-impl
      1.0.0-RC1

  6. There's a list of all blocks, and the syntax for the dependency code is in there someplace.
  7. Once you're done adding dependencies:
    1. If you have a Terminal open with [INFO] Started Jetty Server, close it.
    2. Open a new Terminalcd cocoon

      mvn compileAfter 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






src="/home/YOUR_USER_NAME/myproject/sitemap.xmap" reload-method="synchron"/>

In this case, your project will be found at http://localhost:8888/cocoonTest/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/cocoonTest.