From 51ece6699a4de5905124c4d583a7a72170789eb6 Mon Sep 17 00:00:00 2001
From: "Maria Odea B. Ching" <oching@apache.org>
Date: Mon, 17 Aug 2009 08:35:34 +0000
Subject: [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
---
 archiva-docs/src/site/apt/adminguide/webapp.apt | 63 ++++++++++++++++++++++++-
 1 file 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\>>>>.
-- 
cgit v1.2.3