shannon 2002/06/27 12:40:55
Modified: src/documentation/xdocs/faq faq-configure-environment.xml
Log:
Updated FAQs courtesy of
Luca Morandini ([EMAIL PROTECTED])
plus a few minor copy edits from me.
Revision Changes Path
1.2 +181 -149
xml-cocoon2/src/documentation/xdocs/faq/faq-configure-environment.xml
Index: faq-configure-environment.xml
===================================================================
RCS file:
/home/cvs/xml-cocoon2/src/documentation/xdocs/faq/faq-configure-environment.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- faq-configure-environment.xml 13 May 2002 17:55:25 -0000 1.1
+++ faq-configure-environment.xml 27 Jun 2002 19:40:54 -0000 1.2
@@ -4,111 +4,185 @@
<faqs title="Environment Configuration FAQs">
<faq>
- <question>How could I have my Cocoon app in an URI other than
- <you-server>/cocoon/<my-app>?
+ <question>How can I reach my Cocoon app from an URI other than
+ <your-server>/cocoon/<my-app>?
</question>
<answer>
- <note> This entry refers only to an Apache + Tomcat + Cocoon configuration,
- and was tested under: Windows NT 4.0 + Apache 1.3.14 + Tomcat 3.2 + Cocoon
- 2.0b1.
- </note>
- <p>Test whether Tomcat passes everything under the /cocoon context to
- Cocoon. This may be tested by pointing your browser at
- <your-server>:8080/cocoon/xsp/simple, if a text page named
- "A simple XSP page", everything's fine.
+ <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>
- <p>Now, suppose:</p>
+ <note>
+ This entry was tested under: Windows 2000
+ Professional + IIS 5.0 + Tomcat 4.0.1 + Cocoon 2.0.2.
+ </note>
<ol>
- <li>you have a Cocoon application named "foo" which works fine when
- called with <your-server>:8080/cocoon/foo
+ <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>you want the "foo" app to be called from
- <your-server>:8080/foo instead.
+ <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>The idea is just to redirect the desidered URI (foo) to the one within
- the cocoon context (cocoon/foo).
+ <p>
+ Now, http://www.foo.com/bar/index.html should also work.
</p>
- <p>Since this has to be done before the URI is processed by Tomcat, it is
- just natural to use Apache for this. And, of course the user should not
- notice the redirection.
+ <p>
+ Let us explore the second method (URI rewriting).
</p>
- <p>Apache has an handy feature called mod_rewrite which does just this: URI
- rewriting (see the "URL Rewriting Guide" in the Apache user's guide for
+ <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, hence,
- you should add (on a Windows system) this line to the httpf.conf:
+ <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, most probably, this line is already on the httpd.conf, you
- just have to un-comment it).
+ <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>
- <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 this 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
+ 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 the RewriteLogLevel to
+ 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 foo/(.*) /cocoon/foo/$1 [PT]</source>
- <p>This line instructs Apache to redirect everything under "foo" to
- "cocoon/foo" and passes it on to other processing ("[PT]" option),
+ <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/foo" and to pass it on for other processing ("[PT]" option),
like mod_alias.
</p>
- <p>Now, just restart Apache and point your browser to:</p>
- <source><your-server>:8080/foo/<something>...</source>
- <p>it should work just fine.</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>
</answer>
</faq>
<faq>
- <question>How could I have my Cocoon app in a directory other than
+ <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 refers only to an Apache + Tomcat + Cocoon configuration,
- and was tested under: Windows NT 4.0 + Apache 1.3.14 + Tomcat 3.2 + Cocoon
+ <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>
+ <p>Let's suppose the following.</p>
<ol>
- <li>you have an application called "foo" which works perfectly when
+ <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>
+ <li>
+ You want it to be located under the "c:\foo" directory instead
+ </li>
</ol>
- <p>This could be done pretty easily twisting a little bit the sitemap. The
- idea is to mount the sub-sitemap of the "foo" application on a specific
- location on the file system, rather than under the deafult cocoon context.
+ <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[
+ <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
+]]>
+ </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
- webapps/cocoon/foo directory to the /foo directory, and it should work
+ <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>
@@ -120,115 +194,73 @@
</question>
<answer>
<p>
- You need to use mod_jk. Add the following line to
<code>%APACHE_HOME%\conf\httpd.conf</code>
+ You need to use mod_jk. Add the following line to
<code>%APACHE_HOME%\conf\httpd.conf</code>
</p>
-
- <source>JkMount /cocoon/* ajp12</source>
-
+ <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 the above directives can be added at the
- end of httpd.conf.
+ 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 do I hide "cocoon" in the URL's once I integrate using mod_jk as shown
above?
+ How can I improve performance by making the web-server deliver the static
contents ?
</question>
<answer>
- <p>
- Basically to use <code>http://your.server.org/Foo/welcome</code> (as an
example) instead of
- <code>http://your.server.org/cocoon/Foo/welcome</code>. You need the following
two modifications:
- </p>
- <p>
- Step #1: Add the following lies to to httpd.conf.
- </p>
-
- <source><![CDATA[
-RewriteEngine On
-RewriteLog "/var/log/rewrite.log"
-RewriteLogLevel 0
-RewriteRule ^/Foo /cocoon/Foo/ [R]
-RewriteRule ^/Foo(.*) /cocoon/Foo$1 [R]
-]]></source>
-
- <p>
- The file rewrite.log does not have to be located in <code>/var/log</code>. For
- instance, under Windows NT other locations may be appropriate. The
- RewriteLogLevel should be set 3 for debug purposes. The third line is
- essentially a redirect, so that Foo becomee <code>/cocoon/Foo/</code> with the
- trailing <code>/</code>, without it the request would not map onto
- </p>
-
- <source><![CDATA[
-<map:match pattern="">
- <map:redirect-to uri="welcome" />
-</map:match>]]></source>
-
- <p>
- when you I request <code>http://your.server.org/Foo</code>.
-
- Finally, the last RewriteRule could depend on the local settings.
- The original suggestion by Luca was a single line entry (that replaces
- both RewriteRules above) according to:
- </p>
-
- <source>RewriteRule Foo/(.*) /cocoon/Foo/$1 [PT]</source>
-
- <note>
- This did not work in my case (Slackware Linux with Apache1.3,
- tomcat3.2.2, Cocoon). Again, these RewriteRules may vary somewhat
- depending on the local settings. You may have to experiment a bit.
- </note>
- <p>
- Step #2: Add to the sitemap.xmap in the cocoon directory.
- </p>
-
- <source><![CDATA[
-<map:pipeline>
- <map:match pattern="Foo/**">
- <map:mount uri-prefix="Fru" src="file:///www/Foo/"
- check-reload="yes" reload-method="synchron"/>
- </map:match>
-</map:pipeline>
-]]></source>
-
- <p>
- Here, <code>/www/Foo</code> is a some directory on the local file system where
the
- xml, xsp, .., files of the application Foo live.
- </p>
+ <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>
- How can I run Cocoon without X11. Why is a Display needed?
+ How can I run Cocoon without X11. Why is a Display needed ?
</question>
<answer>
- <p>
- An Xserver is needed due to 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.
- </p>
+ <p>
+ 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.
+ </p>
- <source><![CDATA[
+ <source><![CDATA[
$> Xvfb :1 -screen 0 800x600x8 &
$> export DISPLAY=:1
$> $TOMCAT_HOME/bin/startup.sh -f server.xml
-]]></source>
+]]>
+ </source>
- <p>
- Another solution is to use PJA library. Read 'Linux/Headless/Batik'
- section in the <link href="../installing/index.html">Cocoon installation
guide</link>.
- </p>
+ <p>
+ Another solution is to use PJA library. Read 'Linux/Headless/Batik'
+ section in the <link href="../installing/index.html">Cocoon installation
guide</link>.
+ </p>
</answer>
</faq>
-
-
-
-</faqs>
+</faqs>
\ No newline at end of file
----------------------------------------------------------------------
In case of troubles, e-mail: [EMAIL PROTECTED]
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
