[MRM-1085] CLONE -Failing to startup due to invalid bean definition

o updated documentation for setting appserver.base and appserver.home in Windows
o added more troubleshooting tips for startup errors


git-svn-id: https://svn.apache.org/repos/asf/archiva/trunk@804899 13f79535-47bb-0310-9956-ffa450edef68

1 files changed, 61 insertions, 2 deletions

diff --git a/archiva-docs/src/site/apt/adminguide/webapp.apt b/archiva-docs/src/site/apt/adminguide/webapp.apt
index fa908da11..4cea4008a 100644
--- a/archiva-docs/src/site/apt/adminguide/webapp.apt
+++ b/archiva-docs/src/site/apt/adminguide/webapp.apt
@@ -54,14 +54,39 @@ To deploy Archiva on Tomcat 5.5 and Tomcat 6.0
    Bug 40668}} for a workaround.
 
    * The ${appserver.base} java property is used by the Archiva internal logging configuration to determine where to output its logs to.
-     It is important to define this property either in the $CATALINA_OPTS system environment variable (if Tomcat is being launched via the
+     It is important to define this property either in the $CATALINA_OPTS system environment variable if Tomcat is being launched via the
      command line) or the service properties (if being launched as a service or daemon). The format typically expected is
      -Dappserver.base=<SOMEWHERE>. In this example, we'll put the logs in Tomcat's <<<logs>>> directory so we need to set appserver.base
      property to where Tomcat is installed:
 
 +-----------+
-export CATALINA_OPTS="-Dappserver.home=$CATALINA_HOME -Dappserver.base=$CATALINA_HOME"
+export CATALINA_OPTS="-Dappserver.home=$CATALINA_HOME -Dappserver.base=$CATALINA_HOME" (for UNIX)
+
+OR
+
+set CATALINA_OPTS="-Dappserver.home=%CATALINA_HOME% -Dappserver.base=%CATALINA_HOME%" (for Windows)
++-----------+
+
+   * If setting the ${appserver.base} and ${appserver.home} using the previous step does not work, you can set it in the unpacked Archiva web application's
+     <<<WEB-INF/classes/application.properties>>> as follows:
+
 +-----------+
+# for Windows:
+appserver.base=%CATALINA_HOME%
+appserver.base=%CATALINA_BASE%
+
+# or, for UNIX:
+appserver.base=$CATALINA_HOME
+appserver.home=$CATALINA_BASE
++-----------+
+
+   * When running Tomcat as a <<Windows>> service, you need to edit <<<regedit>>> and then, in
+     <<<HKEY_LOCAL_MACHINE \> SOFTWARE \> Apache Software Foundation \> Procrun 2.0 \> TomcatX \> Parameters \> Java>>>, modify
+     the <<<Options>>> variable. Set the ${appserver.base} property by adding the following parameters at the end:
+
++-----------+
+-Dappserver.base=%CATALINA_HOME% -Dappserver.home=%CATALINA_HOME%
++-----------+     
 
  For more information, see {{{http://cwiki.apache.org/confluence/display/ARCHIVA/Archiva+on+Tomcat} Archiva on Tomcat}} in the wiki.
 
@@ -84,6 +109,40 @@ Configuring and Running Archiva
   
 Troubleshooting
 
+* Error During Startup
+
+  There are cases when the Tomcat logs only shows the following error during startup:
+
++-----------+
+...
+Aug 17, 2009 11:04:02 AM org.apache.catalina.core.StandardContext start
+SEVERE: Error listenerStart
+Aug 17, 2009 11:04:02 AM org.apache.catalina.core.StandardContext start
+SEVERE: Context [/archiva] startup failed due to previous errors
+Aug 17, 2009 11:04:04 AM org.apache.coyote.http11.Http11BaseProtocol start
+...
++-----------+
+
+  One of the common causes for this <<<listenerStart Error>>> is a failure during Spring's initialization. One way to diagnose or confirm the
+  exact cause of the error is by adding the following configuration to the unpacked Archiva webapp's <<<WEB-INF/classes/log4j.xml>>>:
+
++-----------+
+<appender name="console" class="org.apache.log4j.ConsoleAppender">
+  <layout class="org.apache.log4j.PatternLayout">
+    <param name="ConversionPattern" value="%d [%t] %-5p %c %x - %m%n"/>
+  </layout>
+</appender>
+
+<logger name="org.springframework.web">
+  <level value="debug"/>
+  <appender-ref ref="console"/>
+</logger>
++-----------+
+
+   The above configuration directs Spring's output logs to the Tomcat console and be recorded in Tomcat's log files. 
+
+* Diagnosing Errors
+
   One of the least decipherable errors you can get from Tomcat is a <<<404>>> when the deployment fails. In <<<\<tomcat home\>/logs/catalina.out>>>  you will only find that it fails, but not why. Also Archiva's logs will not tell you.
 
   The log messages and stack traces in case of a <<<404>>> can be found in <<<\<tomcat home\>/logs/localhost.\<date\>>>>.