Environment Configuration FAQs

How can I reach my Cocoon app from an URI other than <your-server>/cocoon/<my-app>?

Suppose the following.

1. You have a Cocoon application named "bar" which works fine when called with this URI: http://www.foo.com/cocoon/bar/index.html
2. You want the "bar" app to be called from http://www.foo.com/bar/index.html instead (getting rid of "cocoon").

There are, basically, two methods to achieve this.

1. Set Cocoon as the root servlet in your servlet-container
2. Rewrite the URI in the web-server. (When a user asks for http://www.foo.com/bar/index.html, the web-server redirects him/her to http://www.foo.com/cocoon/bar/index.html

Let us explore the first method (Cocoon as the root servlet).

1. Edit the server.xml file which is located under $TOMCAT_HOME/conf
2. Go to the line containing "Tomcat Root Context". (This should be a comment).
3. Add following line after that comment: <context path="" docBase="/cocoon" debug="0"/>
4. Re-start Tomcat.
5. Try: http://www.foo.com:8080/ and the Cocoon welcome page should appear

Now, http://www.foo.com/bar/index.html should also work.

Let us explore the second method (URI rewriting).

The idea is just to redirect a portion of the desired URI (bar) to the one within the cocoon context (cocoon/bar).

Apache has an handy feature called mod_rewrite that does just this: URI rewriting. (See the "URL Rewriting Guide" in the Apache user's guide for details).

First of all, you should instruct Apache to load the mod_rewrite. Add (on a Windows system) to httpd.conf the following line:

     LoadModule rewrite_module modules/ApacheModuleRewrite.dll
   

(By the way it's quite likely that this line is already on the httpd.conf. You just have to uncomment it).

Add this line to httpd.conf in order to activate mod_rewrite:

     RewriteEngine On
   

It is highly recommended to use the logging option of mod_rewrite, in order to check the correctness of the URI rewriting. Just add these lines to the httpd.conf:

     RewriteLog "C:/logs/rewrite.log"
     RewriteLogLevel 9
   

The first line tells Apache to put the URI rewriting log in the c:\logs\rewrite.log file (which happens to be on a Windows system, of course). The second one tells Apache to record everything mod_rewrite does. If you don't want to log anything, just set RewriteLogLevel to 0.

Now, it's time to do the URI rewriting trick.

     RewriteRule bar/(.*) /cocoon/bar/$1 [PT]
   

This line instructs Apache to redirect everything under "bar" to "cocoon/bar" and to pass it on for other processing ("[PT]" option), like mod_alias.

Just restart Apache and point your browser to:

     <your-server>:8080/bar/<something>
   

It should work just fine.

How could I have my Cocoon app located in a directory other than $TOMCAT_HOME/webapps/cocoon/<my-app>?

Let's suppose the following.

1. You have an application called "foo" which works perfectly when located under the %TOMCAT_HOME%\webapps\cocoon\foo directory.
2. You want it to be located under the "c:\foo" directory instead

This could be accomplished quite easily by twisting the sitemap a little bit. The idea is to mount the sub-sitemap of the "foo" application in a specific location of the file system instead of under the default cocoon context.

Here's the sitemap.xmap fragment used to do this.

<map:pipeline>
 <map:match pattern="foo/**">
  <map:mount uri-prefix="foo" src="file:///c:/foo/"/>
 </map:match>
</map:pipeline>

  

The "file:" type of source instructs Cocoon to search the sub-sitemap under the specified directory (which happens to be "c:\foo", since this is a Windows system). See explanation of file: URLs

Now, you just need to copy everything which was under the %TOMCAT_HOME%\webapps\cocoon\foo directory to the c:\foo directory, and it should work graciously.

How do I integrate Apache Server and Cocoon?

See the Wiki page ApacheModProxy for a thorough discussion of this topic.

Another method is to use mod_jk. Add the following line to %APACHE_HOME%\conf\httpd.conf

      JkMount /cocoon/* ajp12
    

along with other directives that are already listed in mod_jk.conf-auto in the tomcat/conf directory. The above directives can be added at the end of httpd.conf.

How can I improve performance by making the web-server deliver the static contents ?

Fairly easy to do.

1. Put the static contents in a physical directory. (Let's call it "c:\foo\static-stuff". On UNIX it may be "/foo/static-stuff".)
2. Make a virtual directory out of "c:\foo\static-stuff" (or, under UNIX "/foo/static-stuff") in you favorite web-server, and name it "static-foo".
3. Reference the static contents in your Cocoon app by URIs starting with "/static-foo", as in: "/static-foo/images/foo.gif" or "/static-foo/scripts/bar.js"

The web-server will now handle the static contents, leaving Cocoon to take care of the dynamic stuff only, delivering optimal performance.

Why won't my Batik .JPG and .PNG samples work? How can I run Cocoon without X11? Why is a Display needed?

If your Batik .JPG and .PNG samples don't work it is probably because you have not installed and configured a graphics display. You have a couple of options depending on your environment.

If you are using the Sun JDK 1.4 then you can use the 'headless' environment. For more information about this see Headless UNIX and PJA.

Otherwise, an XServer is needed because of the Batik library that FOP uses. Batik uses Java's graphics code, which in turn requires the XServer. If you don't have an XServer on your system and can't set the DISPLAY variable to one, then try out XVFB. XVFB gives you an 'in-memory' XServer, which doesn't require any display hardware to run.

$> Xvfb :1 -screen 0 800x600x8 &
$> export DISPLAY=:1
$> $TOMCAT_HOME/bin/startup.sh -f server.xml

   

See also UNIX with X server.

How can I access Cocoon's status page in a mixed servlet environment where "/" is not mapped to Cocoon (only *.xml, *.xsp)?

Just change the status pipeline so it matches a request with a ".xml" extension:

   <map:match pattern="status.xml">
    <map:generate src="status" type="status"/>
    <map:transform src="welcome/status2html.xsl"/>
    <map:serialize/>
   </map:match>

Then you can access the status page with "status.xml".