-----
 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 checkout the latest code

  Using Subversion, either checkout from {{http://svn.apache.org/repos/asf/maven/archiva/trunk/}} or to get all of Maven 2, checkout from {{http://svn.apache.org/repos/asf/maven/trunks/}}.

To build 

  If this is the first time, and if you've not pulled this down for some other reason then it will save time to do the following first:

    * Download the 1.0 connector zip from: http://java.sun.com/j2ee/connector/download.html

    * Unpack the zip to get the jar

    * Run: mvn install:install-file -DgroupId=javax.resource -DartifactId=connector -Dversion=1.0 -Dpackaging=jar -Dfile=connector.jar

    * Download the 1.0.1B jta zip from: {{http://java.sun.com/products/jta/}}

    * Install it: mvn install:install-file -DgroupId=javax.transaction -DartifactId=jta -Dversion=1.0.1B -Dpackaging=jar -Dfile=jta-1_0_1B-classes.zip 

  Otherwise:

    * Build Archiva: mvn install


To test-deploy Archiva on the embedded Jetty

    * cd archiva-webapp

    * mvn jetty:run


To deploy Archiva to 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 archiva/archiva-webapp/target 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.


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.


Setting up your Archiva instance

   * Goto {{http://localhost:9091/}} if on the embedded Jetty, {{http://localhost:8080/archiva/}} if on Tomcat or {{http://localhost:8080/archiva/}} if on Plexus.

   * 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.

 A useful repository to setup when exploring is your local Maven repository. 

+-------------------------------------------------------------------------+
 Identifier: LOCAL
 Name: Maven2 Local Repository
 Location: $HOME/.m2/repository
+-------------------------------------------------------------------------+


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
+-------------------------------------------------------------------------+