cocoon-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From shan...@apache.org
Subject cvs commit: xml-cocoon2/src/documentation/xdocs/faq faq-configure-environment.xml
Date Thu, 27 Jun 2002 19:40:55 GMT
shannon     2002/06/27 12:40:55

  Modified:    src/documentation/xdocs/faq faq-configure-environment.xml
  Log:
  Updated FAQs courtesy of
  Luca Morandini (luca.morandini1@tin.it)
  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
  -   &lt;you-server&gt;/cocoon/&lt;my-app&gt;?
  + <question>How can I reach my Cocoon app from an URI other than
  +   &lt;your-server&gt;/cocoon/&lt;my-app&gt;?
    </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
  -     &lt;your-server&gt;: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 &lt;your-server&gt;: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
  -       &lt;your-server&gt;:8080/foo instead.
  +     <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>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>&lt;your-server&gt;:8080/foo/&lt;something&gt;...</source>
  -   <p>it should work just fine.</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>
    </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/&lt;my-app&gt;?
    </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:     webmaster@xml.apache.org
To unsubscribe, e-mail:          cocoon-cvs-unsubscribe@xml.apache.org
For additional commands, e-mail: cocoon-cvs-help@xml.apache.org


Mime
View raw message