ASF_20_SRC_AUTO/src/documentation/xdocs/faq/faq-configure-environment.xml - cocoon - Git at Google

 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE faqs PUBLIC "-//APACHE//DTD FAQ V1.0//EN" "../dtd/faq-v10.dtd">

 <faqs title="Environment Configuration FAQs">

 <faq>
  <question>How can I reach my Cocoon app from an URI other than
    &lt;your-server&gt;/cocoon/&lt;my-app&gt;?
  </question>
  <answer>
    <p>
      Suppose the following.
    </p>
    <ol>
      <li>You have a Cocoon application named "bar" which works fine when
        called with this URI: http://www.foo.com/cocoon/bar/index.html
      </li>
      <li>You want the "bar" app to be called from
        http://www.foo.com/bar/index.html instead (getting rid of "cocoon").
      </li>
    </ol>
    <p>
      There are, basically, two methods to achieve this.
    </p>
    <ol>
      <li>
        Set Cocoon as the root servlet in your servlet-container
      </li>
      <li>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
      </li>
    </ol>
    <p>
      Let us explore the first method (Cocoon as the root servlet).
    </p>
    <note>
      This entry was tested under: Windows 2000
      Professional + IIS 5.0 + Tomcat 4.0.1 + Cocoon 2.0.2.
    </note>
    <ol>
      <li>
        Edit the server.xml file which is located under $TOMCAT_HOME/conf
      </li>
      <li>
        Go to the line containing "Tomcat Root Context". (This should be a comment).
      </li>
      <li>
        Add following line after that comment:
 	   <code>
 	     &lt;context path="" docBase="/cocoon" debug="0"/&gt;
 	   </code>
      </li>
      <li>
        Re-start Tomcat.
      </li>
      <li>
        Try: http://www.foo.com:8080/ and the Cocoon welcome page should appear
      </li>
    </ol>
    <p>
      Now, http://www.foo.com/bar/index.html should also work.
    </p>
    <p>
      Let us explore the second method (URI rewriting).
    </p>
    <note> This entry was tested under: Windows NT 4.0 + Apache 1.3.14 + Tomcat 3.2 +
      Cocoon 2.0b1. It is Apache-specific.
    </note>
    <p>
      The idea is just to redirect a portion of the desired URI (bar) to the one within
      the cocoon context (cocoon/bar).
    </p>
    <p>
      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).
    </p>
    <p>
      First of all, you should instruct Apache to load the mod_rewrite.
      Add (on a Windows system) to httpd.conf the following line:
    </p>
    <source>
      LoadModule rewrite_module modules/ApacheModuleRewrite.dll
    </source>
    <p>
      (By the way it's quite likely that this line is already on the httpd.conf. You
      just have to uncomment it).
    </p>
    <p>
      Add this line to httpd.conf in order to activate mod_rewrite:
    </p>
    <source>
      RewriteEngine On
    </source>
    <p>
      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:
    </p>
    <source>
      RewriteLog "C:/logs/rewrite.log"
      RewriteLogLevel 9
    </source>
    <p>
      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.
    </p>
    <p>
      Now, it's time to do the URI rewriting trick.
    </p>
    <source>
      RewriteRule bar/(.*) /cocoon/bar/$1 [PT]
    </source>
    <p>
      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.
    </p>
    <p>
      Just restart Apache and point your browser to:
    </p>
    <source>
      &lt;your-server&gt;:8080/bar/&lt;something&gt;
    </source>
    <p>
      It should work just fine.
    </p>
    <note>
 	 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]
    </note>
    <note>
 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.
   </note>
  </answer>
 </faq>

 <faq>
  <question>How could I have my Cocoon app located in a directory other than
    $TOMCAT_HOME/webapps/cocoon/&lt;my-app&gt;?
  </question>
  <answer>
    <note>
      This entry was tested under Windows NT 4.0 + Apache 1.3.14 + Tomcat 3.2 + Cocoon
      2.0b1.
    </note>
    <p>Let's suppose the following.</p>
    <ol>
      <li>
        You have an application called "foo" which works perfectly when
        located under the %TOMCAT_HOME%\webapps\cocoon\foo directory.
      </li>
      <li>
        You want it to be located under the "c:\foo" directory instead
     </li>
    </ol>
    <p>
      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.
    </p>
    <p>
      Here's the sitemap.xmap fragment used to do this.
    </p>
    <source>
 <![CDATA[
 <map:pipeline>
  <map:match pattern="foo/**">
   <map:mount uri-prefix="foo" src="file:///c:/foo/"/>
  </map:match>
 </map:pipeline>
 ]]>
   </source>
    <p>
      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
      <link href="../userdocs/concepts/sitemap.html#file-url">file: URLs</link>
    </p>
    <p>
      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.
    </p>
  </answer>
 </faq>

 <faq>
   <question>
     How do I integrate Apache Server and Cocoon?
   </question>
   <answer>
     <p>
       See the Wiki page
       <link href="http://wiki.cocoondev.org/Wiki.jsp?page=ApacheModProxy">ApacheModProxy</link>
       for a thorough discussion of this topic.
     </p>
     <p>
       Another method is to use mod_jk. Add the following line to
       <code>%APACHE_HOME%\conf\httpd.conf</code>
     </p>
     <source>
       JkMount /cocoon/* ajp12
     </source>
     <p>
       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.
     </p>
   </answer>
 </faq>

 <faq>
   <question>
     How can I improve performance by making the web-server deliver the static contents ?
   </question>
   <answer>
 	<p>
 	  Fairly easy to do.
 	</p>
    <ol>
      <li>
        Put the static contents in a physical directory. (Let's call it "c:\foo\static-stuff".
        On UNIX it may be "/foo/static-stuff".)
 	 </li>
      <li>
        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".
 	 </li>
      <li>
 	   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"
 	 </li>
    </ol>
 	<p>
 	  The web-server will now handle the static contents, leaving Cocoon to take care of the
 	  dynamic stuff only, delivering optimal performance.
 	</p>
   </answer>
 </faq>

 <faq>
   <question>
     Why won't my Batik .JPG and .PNG samples work? How can I run Cocoon without X11?
     Why is a Display needed?
   </question>
   <answer>
    <p>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.
    </p>
    <p>If you are using the Sun JDK 1.4 then you can use the 'headless' environment.
      For more information about this see
      <link href="../installing/index.html#Headless+UNIX+and+PJA">Headless UNIX and PJA</link>.
    </p>
    <p>
      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.
    </p>

    <source><![CDATA[
 $> Xvfb :1 -screen 0 800x600x8 &
 $> export DISPLAY=:1
 $> $TOMCAT_HOME/bin/startup.sh -f server.xml
 ]]>
    </source>
    <p>See also <link href="../installing/index.html#UNIX+with+X+server">UNIX with X server</link></p>
   </answer>
 </faq>

 <faq>
   <question>
     How can I access Cocoon's status page in a mixed servlet environment
     where "/" is not mapped to Cocoon (only *.xml, *.xsp)?
   </question>
   <answer>
   <p>
 Just change the status pipeline so it matches a request with a ".xml" extension:
   </p>

    <source><![CDATA[
    <map:match pattern="status.xml">
     <map:generate src="status" type="status"/>
     <map:transform src="welcome/status2html.xsl"/>
     <map:serialize/>
    </map:match>
 ]]></source>
   <p>
 Then you can access the status page with "status.xml".
   </p>
 </answer>
 </faq>

 </faqs>
	<?xml version="1.0" encoding="UTF-8"?>
	<!DOCTYPE faqs PUBLIC "-//APACHE//DTD FAQ V1.0//EN" "../dtd/faq-v10.dtd">

	<faqs title="Environment Configuration FAQs">

	<faq>
	<question>How can I reach my Cocoon app from an URI other than
	<your-server>/cocoon/<my-app>?
	</question>
	<answer>
	<p>
	Suppose the following.
	</p>
	<ol>
	<li>You have a Cocoon application named "bar" which works fine when
	called with this URI: http://www.foo.com/cocoon/bar/index.html
	</li>
	<li>You want the "bar" app to be called from
	http://www.foo.com/bar/index.html instead (getting rid of "cocoon").
	</li>
	</ol>
	<p>
	There are, basically, two methods to achieve this.
	</p>
	<ol>
	<li>
	Set Cocoon as the root servlet in your servlet-container
	</li>
	<li>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
	</li>
	</ol>
	<p>
	Let us explore the first method (Cocoon as the root servlet).
	</p>
	<note>
	This entry was tested under: Windows 2000
	Professional + IIS 5.0 + Tomcat 4.0.1 + Cocoon 2.0.2.
	</note>
	<ol>
	<li>
	Edit the server.xml file which is located under $TOMCAT_HOME/conf
	</li>
	<li>
	Go to the line containing "Tomcat Root Context". (This should be a comment).
	</li>
	<li>
	Add following line after that comment:
	<code>
	<context path="" docBase="/cocoon" debug="0"/>
	</code>
	</li>
	<li>
	Re-start Tomcat.
	</li>
	<li>
	Try: http://www.foo.com:8080/ and the Cocoon welcome page should appear
	</li>
	</ol>
	<p>
	Now, http://www.foo.com/bar/index.html should also work.
	</p>
	<p>
	Let us explore the second method (URI rewriting).
	</p>
	<note> This entry was tested under: Windows NT 4.0 + Apache 1.3.14 + Tomcat 3.2 +
	Cocoon 2.0b1. It is Apache-specific.
	</note>
	<p>
	The idea is just to redirect a portion of the desired URI (bar) to the one within
	the cocoon context (cocoon/bar).
	</p>
	<p>
	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).
	</p>
	<p>
	First of all, you should instruct Apache to load the mod_rewrite.
	Add (on a Windows system) to httpd.conf the following line:
	</p>
	<source>
	LoadModule rewrite_module modules/ApacheModuleRewrite.dll
	</source>
	<p>
	(By the way it's quite likely that this line is already on the httpd.conf. You
	just have to uncomment it).
	</p>
	<p>
	Add this line to httpd.conf in order to activate mod_rewrite:
	</p>
	<source>
	RewriteEngine On
	</source>
	<p>
	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:
	</p>
	<source>
	RewriteLog "C:/logs/rewrite.log"
	RewriteLogLevel 9
	</source>
	<p>
	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.
	</p>
	<p>
	Now, it's time to do the URI rewriting trick.
	</p>
	<source>
	RewriteRule bar/(.*) /cocoon/bar/$1 [PT]
	</source>
	<p>
	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.
	</p>
	<p>
	Just restart Apache and point your browser to:
	</p>
	<source>
	<your-server>:8080/bar/<something>
	</source>
	<p>
	It should work just fine.
	</p>
	<note>
	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]
	</note>
	<note>
	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.
	</note>
	</answer>
	</faq>

	<faq>
	<question>How could I have my Cocoon app located in a directory other than
	$TOMCAT_HOME/webapps/cocoon/<my-app>?
	</question>
	<answer>
	<note>
	This entry was tested under Windows NT 4.0 + Apache 1.3.14 + Tomcat 3.2 + Cocoon
	2.0b1.
	</note>
	<p>Let's suppose the following.</p>
	<ol>
	<li>
	You have an application called "foo" which works perfectly when
	located under the %TOMCAT_HOME%\webapps\cocoon\foo directory.
	</li>
	<li>
	You want it to be located under the "c:\foo" directory instead
	</li>
	</ol>
	<p>
	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.
	</p>
	<p>
	Here's the sitemap.xmap fragment used to do this.
	</p>
	<source>
	<![CDATA[
	<map:pipeline>
	<map:match pattern="foo/**">
	<map:mount uri-prefix="foo" src="file:///c:/foo/"/>
	</map:match>
	</map:pipeline>
	]]>
	</source>
	<p>
	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
	<link href="../userdocs/concepts/sitemap.html#file-url">file: URLs</link>
	</p>
	<p>
	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.
	</p>
	</answer>
	</faq>

	<faq>
	<question>
	How do I integrate Apache Server and Cocoon?
	</question>
	<answer>
	<p>
	See the Wiki page
	<link href="http://wiki.cocoondev.org/Wiki.jsp?page=ApacheModProxy">ApacheModProxy</link>
	for a thorough discussion of this topic.
	</p>
	<p>
	Another method is to use mod_jk. Add the following line to
	<code>%APACHE_HOME%\conf\httpd.conf</code>
	</p>
	<source>
	JkMount /cocoon/* ajp12
	</source>
	<p>
	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.
	</p>
	</answer>
	</faq>

	<faq>
	<question>
	How can I improve performance by making the web-server deliver the static contents ?
	</question>
	<answer>
	<p>
	Fairly easy to do.
	</p>
	<ol>
	<li>
	Put the static contents in a physical directory. (Let's call it "c:\foo\static-stuff".
	On UNIX it may be "/foo/static-stuff".)
	</li>
	<li>
	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".
	</li>
	<li>
	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"
	</li>
	</ol>
	<p>
	The web-server will now handle the static contents, leaving Cocoon to take care of the
	dynamic stuff only, delivering optimal performance.
	</p>
	</answer>
	</faq>

	<faq>
	<question>
	Why won't my Batik .JPG and .PNG samples work? How can I run Cocoon without X11?
	Why is a Display needed?
	</question>
	<answer>
	<p>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.
	</p>
	<p>If you are using the Sun JDK 1.4 then you can use the 'headless' environment.
	For more information about this see
	<link href="../installing/index.html#Headless+UNIX+and+PJA">Headless UNIX and PJA</link>.
	</p>
	<p>
	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.
	</p>

	<source><![CDATA[
	$> Xvfb :1 -screen 0 800x600x8 &
	$> export DISPLAY=:1
	$> $TOMCAT_HOME/bin/startup.sh -f server.xml
	]]>
	</source>
	<p>See also <link href="../installing/index.html#UNIX+with+X+server">UNIX with X server</link></p>
	</answer>
	</faq>

	<faq>
	<question>
	How can I access Cocoon's status page in a mixed servlet environment
	where "/" is not mapped to Cocoon (only .xml, .xsp)?
	</question>
	<answer>
	<p>
	Just change the status pipeline so it matches a request with a ".xml" extension:
	</p>

	<source><![CDATA[
	<map:match pattern="status.xml">
	<map:generate src="status" type="status"/>
	<map:transform src="welcome/status2html.xsl"/>
	<map:serialize/>
	</map:match>
	]]></source>
	<p>
	Then you can access the status page with "status.xml".
	</p>
	</answer>
	</faq>

	</faqs>