Applying Daniel Mohni's excellent documentation on using Archiva from Maven.

git-svn-id: https://svn.apache.org/repos/asf/maven/archiva/trunk@479011 13f79535-47bb-0310-9956-ffa450edef68

2 files changed, 172 insertions, 0 deletions

diff --git a/src/site/apt/guides/getting-started/maven-configuration.apt b/src/site/apt/guides/getting-started/maven-configuration.apt
new file mode 100644
index 000000000..7d498c0c9
--- /dev/null
+++ b/src/site/apt/guides/getting-started/maven-configuration.apt
@@ -0,0 +1,171 @@
+ -----
+ Client Configuration
+ -----
+ -----
+ 17 November 2006
+ -----
+
+~~ Copyright 2006 The Apache Software Foundation.
+~~
+~~ Licensed 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
+
+  <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/URL-NAME</url>
+    <releases>
+      <enabled>true</enabled>
+    </releases>
+    <snapshots>
+      <enabled>false</enabled>
+    </snapshots>
+  </repository>
++-------------------------------------------------------------------------+
+
+  You can also copy this for a proxied repository, but make sure to change /repository/ to /proxy/ and to change from the "URL Name" to the "Repository Identifier". This should look much like this:
+  
++-------------------------------------------------------------------------+
+  <repository>
+    <id>maven-release</id>
+    <url>URL-TO-ARCHIVA/proxy/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>
++-------------------------------------------------------------------------+
+
+  [[4]] 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>
++-------------------------------------------------------------------------+
+
+  [[5]] 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-1</version>
+        </extension>
+      </extensions>
+    </build>
+    ...
+  </project>
++-------------------------------------------------------------------------+
+
+  [[6]] Finally the user that is running archiva (tomcat-user, plexus-user,..) must have write access to the deployment repository.   
diff --git a/src/site/site.xml b/src/site/site.xml
index 9ac73bd7b..547c61c58 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -26,6 +26,7 @@
         <item name="Welcome"    href="/index.html"/>
         <item name="Getting Started"    href="/guides/getting-started/index.html"/>
         <item name="Getting Started FAQ"    href="/guides/getting-started/faq.html"/>
+        <item name="Maven Configuration"   href="/guides/getting-started/maven-configuration.html"/>
         <item name="Developing"    href="/guides/developing/index.html"/>
     </menu>