From 0cc815a3e821f0a77348b1326aa2c74510c7cd4f Mon Sep 17 00:00:00 2001 From: Brett Porter Date: Fri, 23 Nov 2007 01:02:15 +0000 Subject: [PATCH] commit some docs git-svn-id: https://svn.apache.org/repos/asf/maven/archiva/trunk@597520 13f79535-47bb-0310-9956-ffa450edef68 --- .../apt/adminguide/configuration-files.apt | 62 ++++++++++++++++++- .../src/site/apt/adminguide/configuration.apt | 14 ++++- .../src/site/apt/adminguide/databases.apt | 37 ++++++++++- .../src/site/apt/adminguide/index.apt | 20 +++++- .../src/site/apt/adminguide/installing.apt | 10 ++- .../site/apt/adminguide/network-proxies.apt | 15 ++++- .../site/apt/adminguide/proxy-connectors.apt | 58 ++++++++++++++++- .../src/site/apt/adminguide/security.apt | 1 + .../src/site/apt/adminguide/standalone.apt | 1 + .../src/site/apt/adminguide/webapp.apt | 1 + archiva-docs/src/site/apt/index.apt | 4 +- archiva-docs/src/site/apt/release-notes.apt | 20 +++++- archiva-docs/src/site/apt/userguide/index.apt | 17 ++++- 13 files changed, 244 insertions(+), 16 deletions(-) diff --git a/archiva-docs/src/site/apt/adminguide/configuration-files.apt b/archiva-docs/src/site/apt/adminguide/configuration-files.apt index 8f9518389..a26775cb4 100644 --- a/archiva-docs/src/site/apt/adminguide/configuration-files.apt +++ b/archiva-docs/src/site/apt/adminguide/configuration-files.apt @@ -4,5 +4,65 @@ Configuration Files of Apache Archiva - :STUB: This is a documentation stub. + While Archiva is primarily configured via the graphical administration interface, it stores all configuration in XML configuration + files that can be hand edited and used for backup and migration. + The following files compose the configuration for Archiva: + + * <<>> - this is the primary Archiva configuration file + + * <<>> - this configures the security as described in the {{{security.html} security configuration documentation}} + + * <<>> - only applies when running the standalone Archiva instance, as described in the {{{standalone.html} installing Archiva standalone documentation}} + + This section will focus on the <<>> file. + +* The Archiva configuration file + + The Archiva configuration file is stored in one of two locations: + + * The application server configuration directory (see {{{standalone.html} installing Archiva standalone}} for more information) + + * The user home directory (<<<~/.m2/archiva.xml>>>). + + [] + + When modified in the GUI, the file is written back to the location it was initially read from, with the home directory taking priority if both exist. When using a + standalone installation, it is highly recommended that a configuration file is only maintained in one of the locations. + + The following shows a basic configuration file: + +---- + + 2 + + + ${appserver.base}/repositories/internal + 30 + internal + Archiva Managed Internal Repository + + + + + http://repo1.maven.org/maven2 + central + Central Repository + + + + + internal + central + + always + fix + never + no + + + + +---- + + ~~TODO: need a full reference diff --git a/archiva-docs/src/site/apt/adminguide/configuration.apt b/archiva-docs/src/site/apt/adminguide/configuration.apt index 990b1a810..ee0e6c769 100644 --- a/archiva-docs/src/site/apt/adminguide/configuration.apt +++ b/archiva-docs/src/site/apt/adminguide/configuration.apt @@ -4,5 +4,17 @@ Runtime Configuration of Apache Archiva - :STUB: This is a documentation stub. + Archiva is primarily configured via the graphical administration interface. + + The following describe the various sections of the administration menu: + + * {{{repositories.html} Configuring repositories}} + + * {{{proxy-connectors.html} Configuring proxy connectors}} + + * {{{network-proxies.html} Configuring network proxies}} + + * {{{consumers.html} Configuring repository scanning and consumers}} + + [] diff --git a/archiva-docs/src/site/apt/adminguide/databases.apt b/archiva-docs/src/site/apt/adminguide/databases.apt index b1e001231..6898a327f 100644 --- a/archiva-docs/src/site/apt/adminguide/databases.apt +++ b/archiva-docs/src/site/apt/adminguide/databases.apt @@ -4,8 +4,39 @@ Apache Archiva Databases - :STUB: This is a documentation stub. + Archiva uses an external database for two purposes: -~~TODO: give general information on configuration for an external database -~~TODO: use mysql or external derby as an example + * Storing artifact information + + * As a default user store for security + + [] + + Generally, it is unnecessary to configure anything - the built in embedded database is suitable for the artifact management, and if + an external authentication mechanism is not needed, the user database. + + However, it is possible to configure an external database as needed. + +* Configuring an external database + + Archiva uses JNDI data sources to locate the databases to use: + + * <<>> - the repository database + + * <<>> - the user store + + Configuring an external database for either or both of these sources depends is configured in <<>> if you are using the + {{{standalone.html} standalone installation}}, or in the application server configuration if you are using the {{{webapp.html} web application + installation}}. + +* Backing up the database + + While it is a good idea to back up both databases, it is not strictly necessary to back up the repository database on a regular basis. Should any + data loss be suffered, this database can be regenerated by deleting it's contents and re-scanning the repositories. + + If you are using the default user security mechanism, it is important to back up the users database on a regular basis to ensure that the user + passwords and information are not lost in the event of corruption. With the default embedded storage this is simply a matter of making a copy of + the database directory on the filesystem. If you have configured an external database as the source for user information, please refer to your + database documentation for backup instructions. + ~~TODO: link to wiki location that does others diff --git a/archiva-docs/src/site/apt/adminguide/index.apt b/archiva-docs/src/site/apt/adminguide/index.apt index 9f255f611..771f900cb 100644 --- a/archiva-docs/src/site/apt/adminguide/index.apt +++ b/archiva-docs/src/site/apt/adminguide/index.apt @@ -4,5 +4,23 @@ System Administrators Guide to Apache Archiva - :STUB: This is a documentation stub. + Archiva is designed to be simple to install and maintain - including both manual configuration files and a comprehensive + graphical administration interface. + + The following sections describe the process for configuring Archiva for use: + + * {{{installing.html} Installing Archiva}} + + * {{{databases.html} Configuring databases for Archiva}} + + * {{{security.html} Configuring security for Archiva}} + + * {{{configuration.html} Using the graphical administration interface}} + + * {{{configuration-files.html} The configuration files available for Archiva}} + + * {{{reports.html} Repository health reports}} + + [] + diff --git a/archiva-docs/src/site/apt/adminguide/installing.apt b/archiva-docs/src/site/apt/adminguide/installing.apt index 4005854f6..1aba9bd96 100644 --- a/archiva-docs/src/site/apt/adminguide/installing.apt +++ b/archiva-docs/src/site/apt/adminguide/installing.apt @@ -4,6 +4,12 @@ Installing Apache Archiva - :STUB: This is a documentation stub. + Whether you choose to install Archiva as a standalone application or as a web application in your preferred Java EE + application server, only a minimal amount of configuration is necessary. + + The following documents cover the different installation alternatives: + + * {{{standalone.html} Installing standalone}} + + * {{{webapp.html} Installing as a web application}} -~~TODO: ensure upgrading is covered - does it need to be a separate doc diff --git a/archiva-docs/src/site/apt/adminguide/network-proxies.apt b/archiva-docs/src/site/apt/adminguide/network-proxies.apt index ba04fc4d6..320cac109 100644 --- a/archiva-docs/src/site/apt/adminguide/network-proxies.apt +++ b/archiva-docs/src/site/apt/adminguide/network-proxies.apt @@ -4,5 +4,18 @@ Understanding Network Proxy Configuration of Apache Archiva - :STUB: This is a documentation stub. + Archiva uses the terminology "proxy" for two different concepts: + + * The remote repository proxying cache, as configured through {{{proxy-connectors.html} proxy connectors}} between repositories + + * Network proxies, which are traditional protocol based proxies (primarily for HTTP access to remote repositories over a firewall) + + [] + + Network proxies are configured using standard HTTP proxy settings as provided by your network administrator. + + Once configured, the network proxy can be attached to operations that access remote resources. At present, this is configured on the + remote repository proxy connectors that need to access the remote repository over the HTTP protocol. + + ~~TODO: walkthrough configuration diff --git a/archiva-docs/src/site/apt/adminguide/proxy-connectors.apt b/archiva-docs/src/site/apt/adminguide/proxy-connectors.apt index 0502b0ed4..cf4dd72a3 100644 --- a/archiva-docs/src/site/apt/adminguide/proxy-connectors.apt +++ b/archiva-docs/src/site/apt/adminguide/proxy-connectors.apt @@ -4,5 +4,61 @@ Understanding Proxy Connector Configuration of Apache Archiva - :STUB: This is a documentation stub. + Archiva uses the terminology "proxy" for two different concepts: + + * The remote repository proxying cache, as configured through proxy connectors between repositories + + * {{{network-proxies.html} Network proxies}}, which are traditional protocol based proxies (primarily for HTTP access to remote repositories over a firewall) + + [] + + A proxy connector is used to link a managed repository (stored on the Archiva machine) to a remote repository (accessed via a URL). This will mean that when a request + is received by the managed repository, the connector is consulted to decide whether it should request the resource from the remote repository (and potentially cache + the result locally for future requests). + + Each managed repository can proxy multiple remote repositories to allow grouping of repositories through a single interface inside the Archiva instance. For instance, + it is common to proxy all remote releases through a single repository for Archiva, as well as a single snapshot repository for all remote snapshot repositories. + + A basic proxy connector configuration simply links the remote repository to the managed repository (with an optional network proxy for access through a firewall). + However, the behaviour of different types of artifacts and paths can be specifically managed by the proxy connectors to make access to remote repositories more flexibly controlled. + +* Configuring policies + + When an artifact is requested from the managed repository and a proxy connector is configured, the policies for the connector are first consulted to decide whether + to retrieve and cache the remote artifact or not. Which policies are applied depends on the type of artifact. + + By default, Archiva comes with the following policies: + + * <<>> - how to behave for released artifact metadata (those not carrying a <<>> version). This can be set to <<>> (default), <<>>, <<>>, <<>> and <<>>. + + * <<>> - how to behave for snapshot artifact metadata (those carrying a <<>> version). This can be set to <<>> (default), <<>>, <<>>, <<>> and <<>>. + + * <<>> - how to handle incorrect checksums when downloading an artifact from the remote repository (ie, the checksum of the artifact does not match the corresponding detached checksum file). + The options are to fail the request for the remote artifact, fix the checksum on the fly (default), or simply ignore the incorrect checksum + + * <<>> - whether failures retrieving the remote artifact should be cached (to save network bandwidth for missing or bad artifacts), or uncached (default). + + [] + +* Configuring whitelists and blacklists + + By default, all artifact requests to the managed repository are proxied to the remote repository via the proxy connector if the policies pass. However, it can be more efficient to + configure whitelists and blacklists for a given remote repository that match the expected artifacts to be retrieved. + + If only a whitelist is configured, all requests not matching one of the whitelisted elements will be rejected. Conversely, if only a blacklist is configured, all requests not matching one of + the blacklisted elements will be accepted (while those matching will be rejected). If both a whitelist and blacklist are defined, a path must be listed in the whitelist and not in the blacklist + to be accepted - all other requests are rejected. + + The path in the whitelist or blacklist is a repository path, and not an artifact path, and matches the request and format of the remote repository. The characters <<<*>>> and <<<**>>> are wildcards, + with <<<*>>> matching anything in the current path, while <<<**>>> matches anything in the current path and deeper in the directory hierarchy. + + For instance, to only retrieve artifacts in the Apache group ID from a repository, but no artifacts from the Maven group ID, you would configure the following: + + * White list: <<>> + + * Black list: <<>> + + [] + + ~~TODO: walkthrough configuration diff --git a/archiva-docs/src/site/apt/adminguide/security.apt b/archiva-docs/src/site/apt/adminguide/security.apt index 33770e4b0..3e0ad6668 100644 --- a/archiva-docs/src/site/apt/adminguide/security.apt +++ b/archiva-docs/src/site/apt/adminguide/security.apt @@ -6,3 +6,4 @@ Understanding Apache Archiva Security :STUB: This is a documentation stub. + ~~TODO: walkthrough configuration diff --git a/archiva-docs/src/site/apt/adminguide/standalone.apt b/archiva-docs/src/site/apt/adminguide/standalone.apt index 85ea30a29..bd144c92f 100644 --- a/archiva-docs/src/site/apt/adminguide/standalone.apt +++ b/archiva-docs/src/site/apt/adminguide/standalone.apt @@ -8,4 +8,5 @@ Installing Standalone Distribution of Apache Archiva ~~TODO: link to quick start as it covers the most basic scenario ~~TODO: ensure to refer to advanced configuration options, such as PLEXUS_BASE +~~TODO: upgrading diff --git a/archiva-docs/src/site/apt/adminguide/webapp.apt b/archiva-docs/src/site/apt/adminguide/webapp.apt index 8de31a048..aabcc8eaa 100644 --- a/archiva-docs/src/site/apt/adminguide/webapp.apt +++ b/archiva-docs/src/site/apt/adminguide/webapp.apt @@ -5,6 +5,7 @@ Installing Apache Archiva as a Web Application ~~TODO: link to wiki location for other application servers +~~TODO: upgrading To deploy Archiva on Tomcat 5.5 diff --git a/archiva-docs/src/site/apt/index.apt b/archiva-docs/src/site/apt/index.apt index b9fa61a16..02340d989 100644 --- a/archiva-docs/src/site/apt/index.apt +++ b/archiva-docs/src/site/apt/index.apt @@ -12,9 +12,7 @@ your artifact utilisation with search, browse and reporting, and perform routine maintenance on your repositories. - ~~TODO: improve appearance of links - - To get started with Archiva, read the following documentation: + To get started with Archiva, you can read the following documentation: * {{{quick-start.html} A Quick Getting Started Guide}} diff --git a/archiva-docs/src/site/apt/release-notes.apt b/archiva-docs/src/site/apt/release-notes.apt index ed8c81391..9749a8bd0 100644 --- a/archiva-docs/src/site/apt/release-notes.apt +++ b/archiva-docs/src/site/apt/release-notes.apt @@ -6,6 +6,22 @@ Release Notes for Archiva 1.0 -~~TODO: paste, instructions, etc? + The Apache Archiva team would like to announce the release of Archiva 1.0. + + Archiva 1.0 is {{{/download.html} available for download from the web site}}. + + Archiva is an application for managing one or more remote repositories, including administration, artifact handling, browsing and searching. + + If you have any questions, please consult: + + * the web site: {{http://maven.apache.org/archiva/}} + + * the archiva-user mailing list: {{http://maven.apache.org/archiva/mail-lists.html}} + +* Release Notes + + The full list of changes can be found {{{http://jira.codehaus.org/secure/ReleaseNote.jspa?version=12113&styleName=Text&projectId=10980} in JIRA}} and is reproduced below: + +~~TODO: paste + - {{{http://jira.codehaus.org/secure/ReleaseNote.jspa?version=12113&styleName=Text&projectId=10980} Release Notes from JIRA}} diff --git a/archiva-docs/src/site/apt/userguide/index.apt b/archiva-docs/src/site/apt/userguide/index.apt index 58ef923d2..e8a1c11d8 100644 --- a/archiva-docs/src/site/apt/userguide/index.apt +++ b/archiva-docs/src/site/apt/userguide/index.apt @@ -4,5 +4,20 @@ User Guide - :STUB: This is a documentation stub. + Welcome to the Archiva user's guide. Getting to know and use Archiva is very simple - please select one of the following documents to learn how to use + Archiva quickly. + + * {{{browsing.html} Browsing Archiva repositories}} + + * {{{searching.html} Searchin Archiva repositories}} + + * {{{find-artifact.html} Identifying an unknown artifact by comparing the repository checksum database}} + + * {{{using-repository.html} Using Archiva as a repository for Maven, Ivy, etc.}} + + * {{{deploy.html} Deploying artifacts to the repository}} + + [] + + -- 2.39.5