-----
 Client Configuration
 -----
 -----
 17 November 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

Configuring Maven-2 to use an Archiva repository

  To get your local Maven 2 installation to use an Archiva proxy you need to add the repositories you require to your 'settings.xml'. This file is usually found in ${user.dir}/.m2/settings.xml (see the {{{http://maven.apache.org/settings.html}Settings Reference}}). 
  
  You will need to add one entry for each repository that is setup in Archiva. If your repository contains plugins; remember to also include a <pluginRepository> setting.

  <URL-TO-ARCHIVA> => where to find Archiva eg. http://localhost:8080/archiva
  
  <REPOSITORY-ID> => Identifer for the proxied repository inside Archiva eg. internal, releases

  ~~ <URL-NAME> => Another identifier, this time for normal repositories [one of the these will go away]
  
* Configuring a Repository

  [[1]] create a new profile to setup your repositories

+-------------------------------------------------------------------------+
  <settings>
    ...
    <profiles>
      <profile>
        <id>Repository Proxy</id>
        <activation>
          <activeByDefault>true</activeByDefault>
        </activation>
        <!-- ******************************************************* -->
        <!-- repositories for jar artifacts -->
        <!-- ******************************************************* -->
        <repositories>
          <repository>
            ...
          </repository>
          ...   
        </repositories>
        <!-- ******************************************************* -->
        <!-- repositories for maven plugins -->
        <!-- ******************************************************* -->
        <pluginRepositories>
          <pluginRepository>
            ...
          </pluginRepository>
          ...   
        </pluginRepositories>
      </profile>
      ...
    </profiles>
    ...
  </settings>
+-------------------------------------------------------------------------+

  [[2]] add your repository configuration to the profile...

  You can copy the repository configuration from the POM Snippet on the Archiva Administration Page for a normal repository. It should look much like:

+-------------------------------------------------------------------------+
  <repository>
    <id>repository-1</id>
    <url>URL-TO-ARCHIVA/repository/REPOSITORY-ID</url>
    <releases>
      <enabled>true</enabled>
    </releases>
    <snapshots>
      <enabled>false</enabled>
    </snapshots>
  </repository>
+-------------------------------------------------------------------------+

* Configuring Maven-2 to deploy to an Archiva repository
  
  [[1]] Create a user in Archiva to use for deployment

  [[2]] The deployment user needs the Role 'Repository Manager' for each repository that you want to deploy to

  [[3]] Define the server for deployment inside your 'settings.xml', use the newly created user for authentication

+-------------------------------------------------------------------------+
  <settings>
    ...
    <servers>
      <server>
        <id>deployment.webdav</id>
        <username>{archiva-deployment-user}</username>
        <password>{archiva-deployment-pwd}</password>
      </server>
      ...
    </servers>
    ...
  </settings>
+-------------------------------------------------------------------------+

* Deploying to Archiva

  [[1]] Configure the distributionManagement part of your pom.xml
 
+-------------------------------------------------------------------------+
  <project>
    ...
    <distributionManagement>
      <repository>
        <id>deployment.webdav</id>
        <name>Internal Release Repository</name>
        <url>dav:URL-TO-ARCHIVA/repository/REPOSITORY-ID/</url>
      </repository>
      <snapshotRepository>
        <id>deployment.webdav</id>
        <name>Internal Snapshot Repository</name>
        <url>dav:URL-TO-ARCHIVA/repository/REPOSITORY-ID/</url>
      </snapshotRepository>
    </distributionManagement>
    ...
  </project>
+-------------------------------------------------------------------------+

  [[2]] Add a build extension to your pom.xml to use webdav

+-------------------------------------------------------------------------+
  <project>
    ...
    <build>
      <extensions>
        <extension>
          <groupId>org.apache.maven.wagon</groupId>
          <artifactId>wagon-webdav</artifactId>
          <version>1.0-beta-2</version>
        </extension>
      </extensions>
    </build>
    ...
  </project>
+-------------------------------------------------------------------------+

  [[3]] Finally the user that is running archiva (tomcat-user, plexus-user,..) must have write access to the deployment repository.   
  
* Deploying Third-Party Artifacts to Archiva

  [[1]] In the directory from which you intend to execute "<<<mvn
  deploy:deploy-file>>>", save the following content as <<<pom.xml>>>.
  
+-------+
<project>
   <modelVersion>4.0.0</modelVersion>
   <groupId>com.example</groupId>
   <artifactId>webdav-deploy</artifactId>
   <packaging>pom</packaging>
   <version>1</version>
   <name>Webdav Deployment POM</name>
   
   <build>
      <extensions>
         <extension>
            <groupId>org.apache.maven.wagon</groupId>
            <artifactId>wagon-webdav</artifactId>
            <version>1.0-beta-2</version>
         </extension>
      </extensions>
   </build>

</project>
+-------+

  This pom will not be deployed with the artifact, it simply serves to make the
  wagon-webdav jar available to the build process.
  
  Alternately, save this file somewhere else, and use "<<<mvn ... -f
  /path/to/filename>>>" to force the use of an alternate POM file.
  
  [[2]] Deploy the artifact:
  
+------+
mvn deploy:deploy-file -Dfile=filename.jar -DpomFile=filename.pom
    -DrepositoryId=deployment.webdav
    -Durl=dav:URL-TO-ARCHIVA/repository/REPOSITORY-ID
+------+

Archiva as a Proxy

* Creating a New Proxy Repository
  
  Archiva has pre-configured proxy connectors for the 'internal' managed repo and the 'central' and 'maven2-repository.dev.java.net' remote repositories.
  
  To create a new proxy repository, just do the following:
  
  [[1]] Add a new managed repository
  
  Go to Repositories --> Add (Managed Repository) 
  
  Create the managed repository (let's say 'releases') which would serve as the proxy repo.
  
  Do not forget to set the necessary permissions or user roles in Users Management if you want this repository to be secured.
  
  [[2]] Add a remote repository
  
  Go to Repositories --> Add (Remote Repository)
   
  Add the remote repository you want to proxy.
  
  [[3]] Create a proxy connector
  
  Go to Proxy Connectors --> Add
  
  Fill up the following fields:
  
  * Network Proxy* - if your network connection has a network proxy, then this should be configured via the Network Proxies in Archiva. Select the network proxy, if you're using one, that will be used for this proxy connector. 
  
  * Managed Repository* - the managed repository you want to connect to the remote repository.
  
  * Remote Repository* - the repository you want to proxy
  
  * Policies - the download policies that will be used by Archiva when proxying
  
  * Properties
  
  * Black List Patterns - the patterns that will be blacklisted during proxying
  
  * White List Patterns - the patterns that will be included during proxying
  
* Using the Proxy Repository with Maven
  
  Set-up your settings.xml file as shown above in sections 1 and 2 of Configuring a Repository. In this case, use the repository configuration of the managed repository you've created. 
  
  Then, configure the <server> settings in the settings.xml file as shown below:
  
+-------------------------------------------------------------------------+
  <settings>
    ...
    <servers>
      <server>
        <id>releases</id>
        <username>{archiva-user}</username>
        <password>{archiva-pwd}</password>
      </server>
      ...
    </servers>
    ...
  </settings>
+-------------------------------------------------------------------------+
  
  Execute a Maven 2 build. Artifacts should be downloaded from the proxy repository/repositories you've set in your settings.xml