move the rest of the maven configuration docs

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

2 files changed, 118 insertions, 162 deletions

diff --git a/archiva-docs/src/site/apt/guides/maven-configuration.apt b/archiva-docs/src/site/apt/guides/maven-configuration.apt
deleted file mode 100644
index b107239a1..000000000
--- a/archiva-docs/src/site/apt/guides/maven-configuration.apt
+++ /dev/null
@@ -1,160 +0,0 @@
- -----
- 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>
-+-------------------------------------------------------------------------+
-
-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
-  
-  
diff --git a/archiva-docs/src/site/apt/userguide/using-repository.apt b/archiva-docs/src/site/apt/userguide/using-repository.apt
index 0fff28b49..48ab0a27d 100644
--- a/archiva-docs/src/site/apt/userguide/using-repository.apt
+++ b/archiva-docs/src/site/apt/userguide/using-repository.apt
@@ -2,7 +2,123 @@
  Using as a Repository
  ------
 
-Using as a Repository
+Configuring Maven 2 to use an Archiva repository
 
-  :STUB: This is a documentation stub.
+  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}}). 
+
+  How you configure the settings depends on how you would like to utilise the repository. You can add the Archiva repository as an additional repository to others already declared by the project, or lock down the
+  environment to only use the Archiva repositories (possibly proxying content from a remote repository).
+
+* Locking down to only use Archiva
+
+  If you would like Archiva to serve as the only repository used by your Maven installation, you can use the Maven mirror settings to force this behaviour.
+
+  First, you need to select the default repository to use when none is configured by adding the following to the <<<settings.xml>>> file:
+
++-------------------------------------------------------------------------+
+<settings>
+  ...
+  <mirrors>
+    <mirror>
+      <id>archiva.default</id>
+      <url>http://repo.mycompany.com:8080/archiva/repository/internal/</url>
+      <mirrorOf>*</mirrorOf>
+    </mirror>
+  </mirrors>
+  ...
+</settings>
++-------------------------------------------------------------------------+
+
+  With this in place, all repository requests will be sent to the internal repository (which by default is configured to proxy the central repository).
+
+  If you have separate Archiva repositories that you wish to use, you can add an extra mirror declaration as needed:
+
++-------------------------------------------------------------------------+
+    ...
+    <mirror>
+      <id>archiva.apache.snapshots</id>
+      <url>http://repo.mycompany.com:8080/archiva/repository/snapshots/</url>
+      <mirrorOf>apache.snapshots</mirrorOf>
+    </mirror>
+    ...
++-------------------------------------------------------------------------+
+
+  <<WARNING:>> Maven, as of version 2.0.8, does not properly report the correct URL in errors when a mirror is used - so although the Archiva instance is being consulted any error messages will still reflect
+  the original URL described in the POM.
+
+* Using Archiva as an additional repository
+  
+  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.
+
+  [[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>http://repo.mycompany.com:8080/archiva/repository/internal/</url>
+  <releases>
+    <enabled>true</enabled>
+  </releases>
+  <snapshots>
+    <enabled>false</enabled>
+  </snapshots>
+</repository>
++-------------------------------------------------------------------------+
+
+  [[3]] Add the necessary security configuration
+
+  This is only necessary if the guest account does not have read access to the given repository.
+
++-------------------------------------------------------------------------+
+<settings>
+  ...
+  <servers>
+    <server>
+      <id>repository-1</id>
+      <username>{archiva-user}</username>
+      <password>{archiva-pwd}</password>
+    </server>
+    ...
+  </servers>
+  ...
+</settings>
++-------------------------------------------------------------------------+