• How can I reach my Cocoon app from an URI other than <your-server>/cocoon/<my-app>?
• How could I have my Cocoon app located in a directory other than $TOMCAT_HOME/webapps/cocoon/<my-app>?
• How do I integrate Apache Server and Cocoon?
• How can I improve performance by making the web-server deliver the static contents ?
• How can I run Cocoon without X11. Why is a Display needed ?
• How can I access Cocoon's status page in a mixed servlet environment where "/" is not mapped to Cocoon (only *.xml, *.xsp)?
• How can I add my FAQ to this document?
• How can I suggest improvements to existing FAQs?

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).

This entry was tested under: Windows 2000 Professional + IIS 5.0 + Tomcat 4.0.1 + Cocoon 2.0.2.

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).

This entry was tested under: Windows NT 4.0 + Apache 1.3.14 + Tomcat 3.2 + Cocoon 2.0b1. It is Apache-specific.

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.

The RewriteRule may not work in all cases (notably under Slackware Linux with Apache 1.3), if so, try replacing it with: RewriteRule ^/Foo /cocoon/Foo/ [R] RewriteRule ^/Foo(.*) /cocoon/Foo$1 [R]

Another user adds: In my experience, session support is lost when you use mod_rewrite because the cookie path for the Cocoon session is "/cocoon". Because the browser sees the path differently, the session cookie is not granted access, and sessions don't work. I got around this by renaming Cocoon to ROOT, I imagine setting the default docBase would have the same effect.

This entry was tested under Windows NT 4.0 + Apache 1.3.14 + Tomcat 3.2 + Cocoon 2.0b1.

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.

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.

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.

An Xserver is needed because of the batik library 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

Another solution is to use PJA library. Read 'Linux/Headless/Batik' section in the Cocoon installation guide.

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".

Follow the instructions found in How-To Author an FAQ.

Given the rapid pace of change with Cocoon, many individual FAQs quickly become out-of-date and confusing to new users. If you have the relevant knowledge, please consider updating other FAQs on this page for technical errors. If you see a few typos, please consider fixing them too. Follow the instructions found in How-To Author an FAQ.