-----
 Getting Started with Archiva
 -----
 Henri Yandell
 -----
 1 October 2006
 -----

~~ Licensed to the Apache Software Foundation (ASF) under one
~~ or more contributor license agreements.  See the NOTICE file
~~ distributed with this work for additional information
~~ regarding copyright ownership.  The ASF licenses this file
~~ to you under the Apache License, Version 2.0 (the
~~ "License"); you may not use this file except in compliance
~~ with the License.  You may obtain a copy of the License at
~~
~~   http://www.apache.org/licenses/LICENSE-2.0
~~
~~ Unless required by applicable law or agreed to in writing,
~~ software distributed under the License is distributed on an
~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
~~ KIND, either express or implied.  See the License for the
~~ specific language governing permissions and limitations
~~ under the License.

~~ NOTE: For help with the syntax of this file, see:
~~ http://maven.apache.org/guides/mini/guide-apt-format.html

To deploy Archiva on Plexus

  Plexus is a container developed as a part of Maven. It provides a very simple way to get started with Archiva:

   * Unpack the archiva-plexus-runtime/target/archiva-bin.tar.gz archive into a directory of your choice.

   * Start with: ./bin/plexus.sh start or a platform specific version.

   * A Derby exception "Schema 'SA' does not exist" occurs, but is not of concern.

To deploy Archiva on Tomcat 5.5

   * Create a directory in tomcat called archiva, at the same level as bin, conf, logs and the others.

   * Copy the war file from apps/archiva/lib into the new directory

   * Create a conf/Catalina/localhost/archiva.xml file with the following data:

+-------------------------------------------------------------------------+
 <?xml version="1.0" encoding="UTF-8"?>
 <Context path="/archiva"
          docBase="${catalina.home}/archiva/archiva-webapp-1.0-SNAPSHOT.war">

 <Resource name="jdbc/users" auth="Container" type="javax.sql.DataSource"
           username="sa"
           password=""
           driverClassName="org.apache.derby.jdbc.EmbeddedDriver"
           url="jdbc:derby:database/archiva;create=true" />

 <Resource name="jdbc/archiva" auth="Container" type="javax.sql.DataSource"
           username="sa"
           password=""
           driverClassName="org.apache.derby.jdbc.EmbeddedDriver"
           url="jdbc:derby:database/archiva;create=true" />

 <Resource name="mail/Session" auth="Container"
            type="javax.mail.Session"
            mail.smtp.host="localhost"/>
 </Context>
+-------------------------------------------------------------------------+

   * <<Note>>: Tomcat 5.5.20 and 5.5.23 are missing MailSessionFactory and a
   few other classes.  JNDI mail sessions will <not> work.  Use Tomcat 5.5.17
   instead, or see {{{http://issues.apache.org/bugzilla/show_bug.cgi?id=40668}
   Bug 40668}} for a workaround.

   * Copy $HOME/.m2/org/apache/derby/derby/10.1.3.1/derby-10.1.3.1.jar (or from the remote repository) into the Tomcat
   common/lib

   * To deal with a current bug, you'll also need to add the following to your ${catalina.home}/conf/web.xml in the
   relevant section (search for jspx):

+-------------------------------------------------------------------------+
  <servlet-mapping>
    <servlet-name>jsp</servlet-name>
    <url-pattern>*.jspf</url-pattern>
  </servlet-mapping>
+-------------------------------------------------------------------------+

 When you first start Archiva, you will see an Exception that schema SA does not exist - however it doesn't appear to
 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.

Setting up your Archiva instance

   * Goto {{http://localhost:8080/archiva/}}

   * On the first page - setup your administration user. The password requires a numerical character and must not be
   longer than 8 chars. You'll then need to log in. User 'admin' as the username and the password you've entered.

   * On the second page - setup your first repository. It can be both an m1 and an m2 repository.

   * On the third page - setup your indexing. Mostly this means choosing a directory to put the index in. It'll
   re-index every hour.

Updating Archiva within a Tomcat

  While exploring Archiva, or perhaps while developing with it, you will want to delete the 
  current state. Presuming you followed the instructions above, you will need to remove the 
  following files from the ${catalina.home} directory. Ensure your Tomcat has first been 
  shutdown.

+-------------------------------------------------------------------------+
   # Remove the database
   rm -r bin/database/ bin/derby.log
   # Remove the archiva configuration
   rm $HOME/.m2/archiva.xml
   # Remove the temporary Tomcat files
   rm webapps/archiva/ work/Catalina/localhost/archiva/ logs/*
   # Remove the war file (if you're deploying a new one)
   rm archiva/*.war
+-------------------------------------------------------------------------+