blob: 3f8bdcace9382f51727e320c45495cd0e4151bd8 [file] [log] [blame]
<!DOCTYPE html>
<!--
| Generated by Apache Maven Doxia Site Renderer 1.8.1
| Rendered using Apache Maven Fluido Skin 1.6
-->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="author" content="Olivier Lamy" />
<meta name="Date-Creation-yyyymmdd" content="20121220" />
<meta http-equiv="Content-Language" content="en" />
<title>Archiva Documentation &#x2013; Installing Apache Archiva as a Web Application</title>
<link rel="stylesheet" href="../css/apache-maven-fluido-1.6.min.css" />
<link rel="stylesheet" href="../css/site.css" />
<link rel="stylesheet" href="../css/print.css" media="print" />
<script type="text/javascript" src="../js/apache-maven-fluido-1.6.min.js"></script>
<!-- Google Analytics -->
<script type="text/javascript">
var _gaq = _gaq || [];
_gaq.push(['_setAccount', 'UA-140879-5']);
_gaq.push(['_trackPageview']);
(function() {
var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
})();
</script>
</head>
<body class="topBarDisabled">
<a href="https://github.com/apache/archiva">
<img style="position: absolute; top: 0; right: 0; border: 0; z-index: 10000;"
src="https://s3.amazonaws.com/github/ribbons/forkme_right_gray_6d6d6d.png"
alt="Fork me on GitHub">
</a>
<div class="container-fluid">
<div id="banner">
<div class="pull-left"><a href="http://archiva.apache.org/" id="bannerLeft"><img src="http://archiva.apache.org/images/archiva.png" alt="Apache Archiva"/></a></div>
<div class="pull-right"><a href="http://www.apache.org/" id="bannerRight"><img src="https://www.apache.org/images/asf_logo_wide_2016.png" alt="Apache Software Foundation"/></a></div>
<div class="clear"><hr/></div>
</div>
<div id="breadcrumbs">
<ul class="breadcrumb">
<li class=""><a href="https://www.apache.org" class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li>
<li class=""><a href="../../../index.html" title="Archiva">Archiva</a><span class="divider">/</span></li>
<li class=""><a href="../index.html" title="Archiva Documentation">Archiva Documentation</a><span class="divider">/</span></li>
<li class="active ">Installing Apache Archiva as a Web Application</li>
<li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2019-11-30</li>
<li id="projectVersion" class="pull-right">Version: 3.0.0-SNAPSHOT</li>
</ul>
</div>
<div class="row-fluid">
<div id="leftColumn" class="span2">
<div class="well sidebar-nav">
<ul class="nav nav-list">
<li class="nav-header">Introduction</li>
<li><a href="../quick-start.html" title="Quick Start"><span class="none"></span>Quick Start</a> </li>
<li><a href="../tour/index.html" title="Feature Tour"><span class="none"></span>Feature Tour</a> </li>
<li><a href="../release-notes.html" title="Release Notes"><span class="none"></span>Release Notes</a> </li>
<li><a href="../../../download.html" title="Downloads"><span class="none"></span>Downloads</a> </li>
<li class="nav-header">Users Guide</li>
<li><a href="../userguide/browsing.html" title="Browsing"><span class="none"></span>Browsing</a> </li>
<li><a href="../userguide/searching.html" title="Searching"><span class="none"></span>Searching</a> </li>
<li><a href="../userguide/delete-artifact.html" title="Deleting an Artifact"><span class="none"></span>Deleting an Artifact</a> </li>
<li><a href="../userguide/using-repository.html" title="Using as a repository"><span class="none"></span>Using as a repository</a> </li>
<li><a href="../userguide/deploy.html" title="Deploying to repository"><span class="none"></span>Deploying to repository</a> </li>
<li><a href="../userguide/virtual-repositories.html" title="Configuring Virtual Repositories"><span class="none"></span>Configuring Virtual Repositories</a> </li>
<li><a href="../userguide/rss.html" title="Rss Feeds in Archiva"><span class="none"></span>Rss Feeds in Archiva</a> </li>
<li><a href="../userguide/querying-artifacts.html" title="Querying Artifacts"><span class="none"></span>Querying Artifacts</a> </li>
<li class="nav-header">Administrators Guide</li>
<li><a href="../adminguide/installing.html" title="Installing Archiva"><span class="icon-chevron-down"></span>Installing Archiva</a>
<ul class="nav nav-list">
<li><a href="../adminguide/standalone.html" title="Installing Standalone"><span class="none"></span>Installing Standalone</a> </li>
<li class="active"><a href="#"><span class="none"></span>Installing as a WAR</a>
</li>
<li><a href="../adminguide/upgrade.html" title="Upgrading to a New Version"><span class="none"></span>Upgrading to a New Version</a> </li>
</ul>
</li>
<li><a href="../adminguide/databases.html" title="Databases"><span class="none"></span>Databases</a> </li>
<li><a href="../adminguide/repositories-content-storage.html" title="Repositories Content Storage"><span class="none"></span>Repositories Content Storage</a> </li>
<li><a href="../adminguide/security.html" title="Security"><span class="icon-chevron-right"></span>Security</a> </li>
<li><a href="../adminguide/configuration.html" title="Archiva Configuration"><span class="icon-chevron-right"></span>Archiva Configuration</a> </li>
<li><a href="../adminguide/webservices/rest.html" title="REST Apis"><span class="none"></span>REST Apis</a> </li>
<li><a href="../adminguide/configuration-files.html" title="Configuration Files"><span class="none"></span>Configuration Files</a> </li>
<li><a href="../adminguide/system-status.html" title="System Status"><span class="none"></span>System Status</a> </li>
<li><a href="../adminguide/logging.html" title="Log Files"><span class="icon-chevron-right"></span>Log Files</a> </li>
<li><a href="../adminguide/reports.html" title="Reports"><span class="none"></span>Reports</a> </li>
<li class="nav-header">Customising Archiva</li>
<li><a href="../customising/writing-consumer.html" title="Writing a Consumer Plugin"><span class="none"></span>Writing a Consumer Plugin</a> </li>
<li class="nav-header">More Information</li>
<li><a href="https://cwiki.apache.org/confluence/display/ARCHIVA/Index" class="externalLink" title="Archiva Wiki"><span class="none"></span>Archiva Wiki</a> </li>
<li class="nav-header">ASF</li>
<li><a href="https://www.apache.org/foundation/how-it-works.html" class="externalLink" title="How Apache Works"><span class="none"></span>How Apache Works</a> </li>
<li><a href="https://www.apache.org/foundation/" class="externalLink" title="Foundation"><span class="none"></span>Foundation</a> </li>
<li><a href="https://www.apache.org/foundation/sponsorship.html" class="externalLink" title="Sponsoring Apache"><span class="none"></span>Sponsoring Apache</a> </li>
<li><a href="https://www.apache.org/foundation/thanks.html" class="externalLink" title="Thanks"><span class="none"></span>Thanks</a> </li>
<li class="nav-header">Project Documentation</li>
<li><a href="../project-info.html" title="Project Information"><span class="icon-chevron-right"></span>Project Information</a> </li>
</ul>
<form id="search-form" action="https://www.google.com/search" method="get" >
<input value="https://archiva.apache.org/docs/3.0.0-SNAPSHOT/" name="sitesearch" type="hidden"/>
<input class="search-query" name="q" id="query" type="text" />
</form>
<script type="text/javascript">asyncJs( 'https://cse.google.com/brand?form=search-form' )</script>
<hr />
<div id="poweredBy">
<div class="clear"></div>
<div class="clear"></div>
<div id="twitter">
<a href="https://twitter.com/archiva" class="twitter-follow-button" data-show-count="false" data-align="left" data-size="medium" data-show-screen-name="true" data-lang="en">Follow archiva</a>
<script type="text/javascript">!function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0];if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src="//platform.twitter.com/widgets.js";fjs.parentNode.insertBefore(js,fjs);}}(document,"script","twitter-wjs");</script>
</div>
<div class="clear"></div>
<div class="clear"></div>
<a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"><img class="builtBy" alt="Built by Maven" src="../images/logos/maven-feather.png" /></a>
</div>
</div>
</div>
<div id="bodyColumn" class="span10" >
<div class="section">
<h2><a name="Installing_Apache_Archiva_as_a_Web_Application"></a>Installing Apache Archiva as a Web Application</h2>
<p>Archiva can be deployed as a web application into any Java EE application server. This document will show an example of doing so with Apache Tomcat 5.5, 6.0.x and 7.0.x.</p>
<p>You can find information about additional application servers on <a class="externalLink" href="https://cwiki.apache.org/confluence/display/ARCHIVA/HOWTO+run+Archiva+on+your+Application+Server+or+Database"> the archiva wiki</a>.</p>
<p><b>Note</b>: When you first start Archiva, you will see an Exception that schema SA does not exist - however it doesn't cause a problem. If you use a username other than 'sa', such as 'archiva', then you seem to get the same error but Tomcat fails to start the context and you have to shutdown and restart again.</p></div>
<div class="section">
<h2><a name="To_deploy_Archiva_on_Apache_Tomcat_5.5.2C_6.0_and_7.0.x"></a>To deploy Archiva on Apache Tomcat 5.5, 6.0 and 7.0.x</h2>
<ul>
<li>Create a directory in tomcat called archiva, at the same level as bin, conf, logs and the others.</li>
<li>Copy the war file into the new directory</li>
<li>Create a <tt>&lt;tomcat home&gt;/conf/Catalina/localhost/archiva.xml</tt> file with the following data (replace the database paths with a suitable location). When using Tomcat 6.0+, do not include the first line (XML encoding) in the <tt>archiva.xml</tt> configuration specified below to avoid parsing errors during startup:
<div class="source"><pre class="prettyprint"> &lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
&lt;Context path=&quot;/archiva&quot;
docBase=&quot;${catalina.home}/archiva/apache-archiva-1.1.war&quot;&gt;
&lt;Resource name=&quot;jdbc/users&quot; auth=&quot;Container&quot; type=&quot;javax.sql.DataSource&quot;
username=&quot;sa&quot;
password=&quot;&quot;
driverClassName=&quot;org.apache.derby.jdbc.EmbeddedDriver&quot;
url=&quot;jdbc:derby:/path/to/database/users;create=true&quot; /&gt;
&lt;Resource name=&quot;mail/Session&quot; auth=&quot;Container&quot;
type=&quot;javax.mail.Session&quot;
mail.smtp.host=&quot;localhost&quot;/&gt;
&lt;/Context&gt;</pre></div></li>
<li>Install <tt>derby-10.1.3.1.jar</tt> (or later), <tt>activation-1.1.jar</tt> and <tt>mail-1.4.jar</tt> into the Tomcat 5.5 <tt>common/lib</tt> or Tomcat 6.0 <tt>lib</tt> directory. This is required since the data sources are instantiated before the web application.
<p><b>Note</b>: Tomcat 5.5.20 and 5.5.23 are missing MailSessionFactory and a few other classes. JNDI mail sessions will <i>not</i> work. Use Tomcat 5.5.25 instead, or see <a class="externalLink" href="http://issues.apache.org/bugzilla/show_bug.cgi?id=40668"> Bug 40668</a> for a workaround.</p></li>
<li>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 command line) or the service properties (if being launched as a service or daemon). The format typically expected is -Dappserver.base=<i>SOMEWHERE</i>. In this example, we'll put the logs in Tomcat's <tt>logs</tt> directory so we need to set appserver.base property to where Tomcat is installed:
<div class="source"><pre class="prettyprint">export CATALINA_OPTS=&quot;-Dappserver.home=$CATALINA_HOME -Dappserver.base=$CATALINA_HOME&quot; (for UNIX)
OR
set CATALINA_OPTS=&quot;-Dappserver.home=%CATALINA_HOME% -Dappserver.base=%CATALINA_HOME%&quot; (for Windows)</pre></div></li>
<li>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 <tt>WEB-INF/classes/application.properties</tt> as follows:
<div class="source"><pre class="prettyprint"># for Windows:
appserver.base=%CATALINA_HOME%
appserver.base=%CATALINA_BASE%
# or, for UNIX:
appserver.base=$CATALINA_HOME
appserver.home=$CATALINA_BASE</pre></div></li>
<li>When running Tomcat as a <b>Windows</b> service, you need to edit <tt>regedit</tt> and then, in <tt>HKEY_LOCAL_MACHINE &gt; SOFTWARE &gt; Apache Software Foundation &gt; Procrun 2.0 &gt; TomcatX &gt; Parameters &gt; Java</tt>, modify the <tt>Options</tt> variable. Set the ${appserver.base} property by adding the following parameters at the end:
<div class="source"><pre class="prettyprint">-Dappserver.base=%CATALINA_HOME% -Dappserver.home=%CATALINA_HOME%</pre></div></li></ul>
<p>For more information, see <a class="externalLink" href="http://cwiki.apache.org/confluence/display/ARCHIVA/Archiva+on+Tomcat"> Archiva on Tomcat</a> in the wiki.</p></div>
<div class="section">
<h2><a name="Archiva_Configuration"></a>Archiva Configuration</h2>
<p>Archiva is configured using the <tt>~/.m2/archiva.xml</tt> configuration file by default when using a Java EE application server. </p></div>
<div class="section">
<h2><a name="Upgrading_Archiva"></a>Upgrading Archiva</h2>
<p>To upgrade the Archiva web application, simply replace the web application with an alternative. Since the database and configuration files are stored externally to the application, no further maintainance is needed.</p>
<p>For general information about upgrading Archiva, see the relevant section in the <a href="./standalone.html#Upgrading20Archiva"> Installing standalone</a> guide.</p></div>
<div class="section">
<h2><a name="Configuring_and_Running_Archiva"></a>Configuring and Running Archiva</h2>
<p>Once Archiva is running, it is configured in the same way as the standalone instance. See the <a href="../quick-start.html#Setting20up20your20Archiva20instance"> quick start</a> guide for more information.</p></div>
<div class="section">
<h2><a name="Troubleshooting"></a>Troubleshooting</h2>
<div class="section">
<h3><a name="Error_During_Startup"></a>Error During Startup</h3>
<p>There are cases when the Tomcat logs only shows the following error during startup:</p>
<div class="source"><pre class="prettyprint">...
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
...</pre></div>
<p>One of the common causes for this <tt>listenerStart Error</tt> 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 <tt>WEB-INF/classes/log4j2.xml</tt>:</p>
<div class="source"><pre class="prettyprint"> &lt;appenders&gt;
&lt;Console name=&quot;console&quot; target=&quot;SYSTEM_OUT&quot;&gt;
&lt;PatternLayout pattern=&quot;%d{HH:mm:ss.SSS} [%t] %-5level %logger{36} - %msg%n&quot;/&gt;
&lt;/Console&gt;
&lt;/appenders&gt;
&lt;logger name=&quot;org.springframework.web&quot; level=&quot;debug&quot;&gt;
&lt;appender-ref ref=&quot;console&quot;/&gt;
&lt;/logger&gt;</pre></div>
<p>The above configuration directs Spring's output logs to the Tomcat console and be recorded in Tomcat's log files. </p></div>
<div class="section">
<h3><a name="Diagnosing_Errors"></a>Diagnosing Errors</h3>
<p>One of the least decipherable errors you can get from Tomcat is a <tt>404</tt> when the deployment fails. In <tt>&lt;tomcat home&gt;/logs/catalina.out</tt> you will only find that it fails, but not why. Also Archiva's logs will not tell you.</p>
<p>The log messages and stack traces in case of a <tt>404</tt> can be found in <tt>&lt;tomcat home&gt;/logs/localhost.&lt;date&gt;</tt>.</p></div></div>
</div>
</div>
</div>
<hr/>
<footer>
<div class="container-fluid">
<div class="row-fluid">
<div class="row">
<div class="span6 offset1">Apache Archiva, Archiva, Apache, the Apache feather logo, and the Apache Archiva project logos are trademarks of The Apache Software Foundation.</div>
</div>
<div class="row">
&nbsp;
</div>
<div class="row">
<div class="span6 offset2">
<p>
<a href="https://archiva.apache.org/docs/3.0.0-SNAPSHOT/privacy-policy.html">Privacy Policy</a>
</p>
</div>
</div>
</div>
<div id="ohloh" class="pull-right">
<script type="text/javascript" src="https://www.ohloh.net/p/6670/widgets/project_thin_badge.js"></script>
</div>
</div>
</footer>
</body>
</html>