apache archiva user guide - build business websites web...

documentation

apache archivarepository managerthe complete guide

compiled by build business websites

1 | w w w . b u i l d - b u s i n e s s - w e b s i t e s . c o . u k

https://www.build-business-websites.co.uk/

https://www.build-business-websites.co.uk/

archiva repository manager

Introduction to Apache ArchivaThis Archiva reference is for both users and administrators. The document shows you how to install, configure and use archiva. This document also discusses the key middleware services (and client packages) that communicate with archiva.

These include

1. The Maven 3 Build Tool

2. The Jenkins continuous integration server

3. The Central Maven Repository

4. The Eclipse and IntelliJ development environments (IDE)s

5. The Apache WebServer and the WebDAV protocol.

6. The Apache Subversion Version Control System

7. The Linux (Ubuntu) and Windows Operating Systems

It contains instructions for deploying java archives from a Jenkins continuous integration build or from Maven itself. Primarily, those that depend on your software can access released archive files straight from the repository.


https://www.build-business-websites.co.uk/continuous-integration-pattern/

https://www.build-business-websites.co.uk/how-to-install-jenkins-2-on-ubuntu/

With Archiva, re-using software becomes as simple as adding a dependency snippet to a Maven POM file.

1. How do I install Archiva in 1 MinuteInstalling archiva in one minute requires the following steps.

1. Download the archiva tar.gz file2. Unpack it with tar -xzvf archiva-2-2-1.tar.gz3. Change directory to the bin folder.4. Execute the ./archiva start5. Access archiva with http://localhost:8080/

If you want to change the Archiva port from 8080 – visit the archiva xml file in the conf directory.

2. The Pull Repository SetupDo you have lots of .m2/repository everywhere? Every developer’s IDE, every Jenkins installation, every command line build will create very similar repository directories when building your software. It pays to consolidate all those repositories into a single Archiva or Artifactory or Nexus repository.


https://www.build-business-websites.co.uk/command-line-interface/

The Hourglass Gateway Repository?Think of it like an hour glass! You have lots of maven clients inside and lots of repositories outside. Your commons repository sits at the apex in between both.

You save disk space and bandwidth, and you get consolidated reports (and better control) over who is using which JAR archives where and when.

Setting up the Pull Repository?Change every settings.xml located at either /usr/share/maven/settings.xml or $user.home/.m2/settings.xml.

Add this mirror section within the mirrors tag. <mirror> <id>commons-pull-repository</id> <name>The commons pull repository for production quality artifacts.</name> <url>https://www.build-business-websites.co.uk/repository/commons</url> <mirrorOf>*</mirrorOf> </mirror>

How to set “mirrorOf” access rules?


The mirrorOf tag is how access rules are set. <mirrorOf>*</mirrorOf> is the blanket – use this repository for everything.

Everything is a good idea as any confguration you do to your “one-stop-shop” repository – will apply across the board to all your maven installations.

Think of it like an hour glass! You have lots of maven clients inside and lots of repositories outside. Your commons repository sits at the apex in between both.

1. <mirrorOf>*</mirrorOf> matches everything2. <mirrorOf>external:*</mirrorOf> matches all but localhost and file

repositories3. <mirrorOf>RepoA,RepoB,RepoC</mirrorOf> matches the comma separated

repositories4. <mirrorOf>*,!RepoA</mirrorOf> matches everything except RepoA

Don’t forget that the declaration order matters when you specify multiple comma separated repositories. This first match will be used.

3. The Push Repository SetupA repository fits the producer/consumer pattern like a glove. You pull in (consume) production quality artifacts produced by the outside (and inside) world. You pull in every artefact you need through your pull repository. And the inverse applies.

Does the outside world want to consume your half-baked, shoddy snapshot software?

Obviously no! They want to pull from your sole push repository. They want to pull all the release versions of every archive.


Even inside your business you want to cannibalize (reuse) the high quality software. So your pull repository lists your push repository as an “external repository”.

If your push repository is not world readable – you’ll need your push repository to list your pull repository as one of the “clients” who are allowed to consume the production quality software.

Don’t forget that your push repository needs to push out

1. your build class files in archive form2. your javadoc archives documenting public and protected classes and

methods3. your java source code in case they want to navigate to or debug through.

What not to Push Out?Just because you have it does not mean you must manage it inside a repository. A repository overflowing with unnecessary artifacts is an anti-pattern. Test classes are an example – they do not need to be in a repository because test software is hardly ever imported into a project.

Consider whether you really need to manage

1. archives of test classes2. archives of test documentation and sources3. snapshot archives after a time period (like 3 months)

Concentrate on pushing out high quality well documented software with small interfaces that separate concerns.

Failing to Fail the Build (AntiPattern)


A common anti-pattern are builds that fail only when they fail to compile. Once they are compiled and built they are pushed into the snapshot repository.

Yes every check-in should be a release candidate but a high percentage of release candidates being waved through is a sign of a low quality deployment pipeline.

Set standards for software style, complexity and most importantly, dependency. At the outset all developers must know which components can consume ( couple to ) which components. And vice versa the build should fail when a coupling is made that breaks the architectural model.

Set high standards for test coverage and test code quality. Use unit tests and integration tests. Fail the builds when standards are not met.

Your third repository is your snapshot repository – your day to day repository.

Archiva ConfigurationThis chapter describes the installation and basic configuration of Apache Archiva. Archiva is one of several choices for an artifact repository, an important component of a Maven-based continuous integration build system.

The Archiva Jetty instance starts up with a default HTTP port of 8080. If you want to change this, before startup, modify /ciroot/archiva/conf/jetty.xml. Change the connector configuration's SystemProperty value for jetty.port to a different value, for example, 8081:

For example:

<Call name="addConnector">

<Arg>

<New class="org.mortbay.jetty.nio.SelectChannelConnector">

<Set name="host">


<SystemProperty name="jetty.host"/>

</Set>

<Set name="port">

<SystemProperty name="jetty.port" default="8081"/>

</Set>

Starting the ServerAfter the server is configured, you can start it from the command-line interface.

To start the server:

Run the following command: /ciroot/archiva/bin/archiva start

On 64-bit Linux systems, you may receive an error message similar to this:

./archiva: /ciroot/archiva/bin/./wrapper-linux-x86-32:

/lib/ld-linux.so.2: bad ELF interpreter: No such file or directory

If you receive this error, install the glibc.i686 package (using yum for example) and try again.

Check the log output while the server is starting, to ensure that it starts as expected, by running the following command on the command line:

tail -f /ciroot/archiva/logs/*

After the startup tasks complete, the Archiva server is available in the following location:

http://localhost:8081/archiva

Creating an Administrator UserWhen you visit the Archiva home page for the first time, you are prompted to set the administration password. Specify the full name, email address, and password of the administration user.


Description of the illustration create-admin-user.png

Internal and Snapshot RepositoriesArchiva starts up with two hosted repositories configured:

Internal

The internal repository is for maintaining fixed-version released artifacts deployed by your organization, which includes finished versions of artifacts, versions that are no longer in development, and released versions. Note that in-development versions of the same artifacts may exist in the snapshot repository in the future.

Snapshot

The snapshot repository holds the work-in-progress artifacts, which are denoted with a version with the suffix SNAPSHOT, and artifacts that have not yet been released.

Proxy RepositoryIn addition to hosting your internally deployed artifacts, the internal repository is configured to serve as a proxy for the public Maven Central repository by default. A proxy repository can be used instead of directly referring to a third-party repository. A proxy caches previously requested artifacts locally. This reduces the load on public servers, which is recommended; especially if you run builds from a clean repository. If you place too much load on the public server, it may throttle or ban your host from placing additional requests. For significant build performance improvement, fetch dependencies from a less loaded, more proximate, proxy server.

If you require third party artifacts from other public repositories, then add them to your repository as additional Proxy Connectors.

Configuring Mirror RepositoriesBecause you will typically want to share cached third-party proxied artifacts among multiple repositories, you should separate the cached artifacts from your project artifacts by moving them into a separate repository.


To create mirror repositories:

1. Remove the proxy connections from the internal repository.a. Under the Administration menu, click Proxy Connections.b. Delete the Central Repository and maven2-

repository.dev.java.net proxy connectors by clicking the red X on each entry.

2. Add a new mirror repository.a. From the Administration menu, click Repositories.b. From the top right corner, click Add.c. Specify the following information in the Admin: Add Managed

Repository dialog box: Identifier: mirror Name: Mirror Directory: /ciroot/archiva/data/repositories/mirror Select Releases Included, Block Re-deployment of Released

Artifacts, and Scannable.d. Click Add Repository.

Description of the illustration add-managed_mirrror.png

3. Add proxy connectors to the mirror repository.a. Under the Administration menu, click Proxy Connections.b. Click Add.c. Select mirror in Managed Repository.d. Select central for Remote Repository.e. Click Add Proxy Connector.

For configuring a mirror repository in a remote repository, complete steps 1-3. However, select maven2-repository.dev.java.net in step 1-b.

After completing these steps, you should see the following:


Description of the illustration proxy-conn-list.png

To configure the anonymous guest user to enable read privileges for the new repository:

1. Under the Management menu, click User management.2. Click Guest.3. Click Edit Roles.4. Select the Repository Observer role next to mirror.5. Click Submit to save your changes.


Creating Development, Production, Quality Assurance, and Test RepositoriesYou must create a separate repository for each project that you want to target with a Maven build

To ensure that your Maven builds are using the correct version of files, create, configure, and create a group Maven repository for each target environment.

1. Create a repository:a. From the Administration menu, click Repositories.b. To add a new repository, click Add from the top right corner.c. From the Admin: Add Managed Repository dialog box, specify the

following details: Identifier: Provide an identifier, like dev, prod, qa, or test. Name: Provide a name. Directory: Add a directory path

like /ciroot/archiva/data/repositories/${IDENTIFIER}, where ${IDENTIFIER} matches the string that you provided in Identifier.

Deselect Block Re-deployment of Released Artifacts. Select Releases Included and Scannable.

Description of the illustration add-managed-repo.png

d. Click Add Repository.

2. To configure the anonymous guest user to have read privileges for the new repository:

a. Under Manage, click User Management.b. Select guest.c. Select Edit Roles.d. Select the Repository Observer role next to the appropriate repository

entry.e. Click Submit to save your changes.


3. To create a corresponding group for the new repository:a. In the Administration menu, click Repository Groups.b. In the top right corner, click Add Group.c. In the Identifier field, specify a name that matches the repository that

you created, with the addition of -group, for example, dev-group.d. Click Add Group.e. Select your new repository, like dev, from the drop-down menu next

to Add Repository and click Add Repository.

Repeat steps 3-a to 3-d to add mirror and snapshots.

The following figure shows the Repository Groups page.

4.Description of the illustration admin_repo-group.png

5. Repeat the repository and group creation steps 1-3 for each repository type: test, qa, and prod.

Creating a Deployment Capable UserTo support deployment in your internal repository, you must add at least one user with appropriate permissions:

1. Under Management, click User Management.2. Click Create New User to add a user. Then, specify the required details like

name, email address, and password. After the user is added, you are directed to a Role Administration dialog box for that user.

3. In the Role Administration dialog box, under Resource Roles, select the Repository Manager role for Snapshot and Internal Repositories.


4. Click Submit to save your changes.

Note:

The Repository Manager role, while allowing you to upload artifacts, also allows you to change the repository configuration.

To customize or change the role, in the User Roles section, add a new more limited role and assign it to the appropriate users.

Typically, you want to create a new user for each individual with access to the repository. For Jenkins, to publish build output to the repository, each user who accesses the repository should have their own user id, and you should create an additional user with deployment permissions.

After you have completed installation and configuration of Archiva, you should populate your Archiva repository with your built archives.


Understanding Repository Configuration of Apache Archiva

Archiva has two types of repository configuration: managed repository and remote repository.

Managed RepositoryA managed repository is a repository which resides locally to the server where Archiva is running. It could serve as a proxy repository, an internal deployment repository or a local mirror repository.

Managed repository fields:

identifier - the id of the repository. This must be unique. name - the name of the repository. directory - the location of the repository. If the path specified does not exist, Archiva will

create the missing directories. index directory - the location of the index files generated by Archiva. If no location is

specified, then the index directory (named .indexer) will be created at the root of the repository directory. This directory contains the packaged/bundled index which is consumed by different consumers of the index such as M2Eclipse.

type - the repository layout (maven 2 or maven 1) cron - the cron schedule when repository scanning will be executed. repository purge by days older - the first option for repository purge. Archiva will check

how old the artifact is and if it is older than the set number of days in this field, then the artifact will be deleted respecting the retention count of course. In order to disable the purge by number of days old and set Archiva to purge by retention count, just set the repository purge field to 0. The maximum number of days which can be set here is 1000. See the Repository Purge section below for more details.

repository purge by retention count - the second option for repository purge. When running the repository purge, Archiva will retain only the number of artifacts set for this field for a specific snapshot version. See the Repository Purge section below for more details.

releases included - specifies whether there are released artifacts in the repository. block re-deployment of released artifacts - specifies whether released artifacts that

are already existing in the repository can be overwritten. Note that this only take effects for non-snapshot deployments.

snapshots included - specifies whether there are snapshot artifacts in the repository. scannable - specifies whether the repository can be scanned, meaning it is a local

repository which can be indexed, browsed, purged, etc.


delete released snapshots - specifies whether to remove those snapshot artifacts which already has release versions of it in the repository during repository purge.

Skip Packed Index creation - avoid creation of compressed index for IDE usage.

Each repository has its own http(s)/webdav url. This allows the user to browse and access the repository via http(s)/webdav. The url has the following format:

http://[URL TO ARCHIVA]/repository/[REPOSITORY ID] (e.g. http://localhost:8080/repository/releases).

A pom snippet is also available for each repository. The <distributionManagement> section can be copied and pasted into a project's pom to specify that the project will be deployed in that managed repository. The <repositories> section on the other hand, can be copied and pasted to a project's pom.xml or to Maven's settings.xml to tell Maven to get artifacts from the managed repository when building the project.

Remote RepositoryA remote repository is a repository which resides remotely. These repositories are usually the proxied repositories. See Proxy Connectors on how to proxy a repository.

Remote repository fields:

identifier - the id of the remote repository. name - the name of the remote repository.


url - the url of the remote repository. It is also possible to use a 'file://' url to proxy a local repository. Be careful that if this local repository is a managed repository of archiva which has some proxies connectors, those ones won't be triggered.

username - the username (if authentication is needed) to be used to access the repository.

password - the password (if authentication is needed) to be used to access the repository.

type - the layout (maven 2 or maven 1) of the remote repository. Activate download remote index - to activate downloading remote index to add

available remote artifacts in search queries. Remote index url, can be relative to url - path of the remote index directory. Cron expression - cron expression for downloading remote index (default weekly on

sunday) Directory index storage - path to store index directory, default will be $

{appserver.base}/data/remotes/${repositoryId}/.indexer Download Remote Index Timeout in seconds - read time out for downloading remote

index files (default 300) Network Proxy to Use for download Remote Index - proxy to use for downloading

remote index files. Download Remote Index on Startup - will download remote index on Archiva startup. Additionnal url parameters - key/value pairs to add to url when querying remote

repository. Additionnal Http Headers - key/value pairs to add as http headers when querying

remote repository.


You can also trigger an immediate download of remote index files.

Maven Index from Remote repositoriesSince 1.4-M4: If you have configured download remote index, those files (Maven Indexer project format) will be available in the path http://[URL TO ARCHIVA]/repository/id/.index (you can consume those files for IDE)

Scanning a RepositoryRepository scan can be executed on schedule or it can be explicitly executed by clicking the 'Scan Repository Now' button in the repositories page. By default, Archiva only processes new artifacts in the repository with respect to the last run of the repository scanner. Meaning that if the artifact's last modified date is newer than the last repository scan, then the artifact will be processed. Otherwise, it will be skipped. You can override this behavior and force Archiva to process all artifacts regardless of its age by ticking the 'Process All Artifacts' checkbox in the repositories page and clicking the 'Scan Repository Now' button.


For every artifact found by the repository scanner, processing is done on this artifact by different consumers. Examples of the processing done are: indexing, repository purge and database update. Details about consumers are available in the Consumers page.

Repository PurgeRepository purge is the process of cleaning up the repository of old snapshots. When deploying a snapshot to a repository, Maven deploys the project/artifact with a timestamped version. Doing daily/nightly builds of the project then tends to bloat the repository. What if the artifact is large? Then disk space will definitely be a problem. That's where Archiva's repository purge feature comes in. Given a criteria to use -- by the number of days old and by retention count, it would clean up the repository by removing old snapshots.

Please take note that the by number of days old criteria is activated by default (set to 100 days). In order to de-activate it and use the by retention count criteria, you must set the Repository Purge By Days Older field to 0. Another thing to note here is that if the by number of days old criteria is activated, the retention count would still be respected (See the Repository Purge By Days Older section below for more details) but not the other way around.

Let's take a look at different behaviours for repository purge using the following scenario:

Artifacts in the repository:

../artifact-x/2.0-SNAPSHOT/artifact-x-20061118.060401-2.jar

../artifact-x/2.0-SNAPSHOT/artifact-x-20061118.060401-2.pom





1. Repository Purge By Number of Days Older


Using this criteria for the purge, Archiva will check how old an artifact is and if it is older than the set value in the repository purge by days older field, then the artifact will be deleted respecting the retention count of course.

If repository purge by days older is set to 100 days (with repository purge by retention count field set to 1), and the current date is let's say 03-01-2007, given the scenario above.. the following artifacts will be retained: artifact-x-20070113.034619-3.jar, artifact-x-20070113.034619-3.pom, artifact-x-20070203.028902-4.jar and artifact-x-20070203.028902-4.pom. It is clear in the version timestamps that these 4 artifacts are not more than 100 days old from the current date (which is 03-01-2007 in our example) so they are all retained. In this case the retention count doesn't have any effect since the priority is the age of the artifact.

Now, if the repository purge by days older is set to 30 days (with repository purge by retention count field still set to 1) and the current date is still 03-01-2007, then given the same scenario above.. only the following artifacts will be retained: artifact-x-20070203.028902-4.jar and artifact-x-20070203.028902-4.pom. In this case, we can see that the retained artifacts are still not older by the number of days set in the repository purge by days older field and the retention count is still met.

Now, let's set the repository purge by days older to 10 days (with repository purge by retention count field still set to 1) and the current date is still 03-01-2007, then still given the same repository contents above.. the following artifacts will still be retained: artifact-x-20070203.028902-4.jar and artifact-x-20070203.028902-4.pom. It is clear from the version timestamps that the artifacts ARE MORE THAN the repository purge by days older value, which is 10 days. Why is it still retained? Recall the value of the repository purge by retention count -- 1 :) This ensures that there is ALWAYS 1 artifact timestamped version retained for every unique version snapshot directory of an artifact.

2. Repository Purge By Retention Count

If the repository purge by retention count field is set to 2, then only the artifacts artifact-x-20070113.034619-3.jar, artifact-x-20070113.034619-3.pom, artifact-x-20070203.028902-4.jar and artifact-x-20070203.028902-4.pom will be retained in the repository. The oldest snapshots will be deleted maintaining only a number of snapshots equivalent to the set retention count (regardless of how old or new the artifact is).

Deleting Released SnapshotsYou can also configure Archiva to clean up snapshot artifacts that have already been released. This can be done by ticking the Delete Released Snapshots checkbox in the Repository Configuration form.

Once this feature is enabled, if Archiva encounters a snapshot artifact during repository scanning, it would check all the repositories configured for a released version of that snapshot. If it finds one, then it would delete the entire snapshot version directory.


It should be noted that this feature is entirely separate from the repository purge by number of days older and by retention count.


Understanding Proxy Connector Configuration of Apache ArchivaArchiva uses the terminology "proxy" for two different concepts:

The remote repository proxying cache, as configured through proxy connectors between repositories

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.

Proxy ConnectorsList of proxy connectors

Configuring orderYou can configured repositories order using drag&drop


Configuring policiesWhen 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:

Releases - how to behave for released artifact metadata (those not carrying a SNAPSHOT version). This can be set to always (default), hourly, daily, once and never.

Snapshots - how to behave for snapshot artifact metadata (those carrying a SNAPSHOT version). This can be set to always (default), hourly, daily, once and never.

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

Cache failures - whether failures retrieving the remote artifact should be cached (to save network bandwidth for missing or bad artifacts), or uncached (default).

Return error when - if a remote proxy causes an error, this option determines whether an existing artifact should be returned (error when artifact not already present), or the error passed on regardless (always).

On remote error - if a remote error is encountered, stop causes the error to be returned immediately, queue error will return all errors after checking for other successful remote repositories first, and ignore will disregard ay errors.


Configuring whitelists and blacklistsBy 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: org/apache/** Black list: org/apache/maven/**


Making the most of Reporting in Apache ArchivaArchiva has two types of reports: Repository Statistics and Repository Health. Repository Statistics was just implemented in 1.2.

Repository StatisticsRepository statistics contains the detailed statistics such as number of artifacts, number of groups and projects, etc. of an Archiva managed repository.

Configuring the ReportThe following fields are configurable for Repository Statistics:

1. Repositories to be Compared - the repositories whose latest statistics would be compared. If only one repository is selected, the different statistics based on the executed repository scanning and the specified Start Date and End Date will be shown. Otherwise, the latest statistics of the selected repositories on the specified dates will be displayed.

2. Row Count - the number of rows to be displayed on each page.

3. Start Date - the start date range of the statistics to be displayed.

4. End Date - the end date range of the statistics to be displayed.

Contents of the ReportThe Repository Statistics Show Report button will display a table containing the statistics of the repository/repositories. See below for a sample Repository Statistics report comparing two repositories:


Repository Statistics can be exported to a CSV file. To do this, just click the link on the upper left hand corner above the report.

Repository HealthThe Repository Health report is a detailed listing of the problematic artifacts in the different repositories. Problematic artifacts are those artifacts that were detected by Archiva to have defects (ex. the versions in the pom and in the artifact itself do not match).

Configuring the ReportThere are 3 fields which can be configured when viewing the report. These are: the number of rows per page, the group id and the repository.

1. Setting the row count. This field is for configuring the number of rows or artifacts to be displayed per page of the report. By default, this is set to 100. The minimum number of rows per page is 10 and the maximum number of rows is 1000.

2. Setting the group id. The group id pertains to the group id of the artifact (ex. org.apache.maven.plugins). This field has a blank default value -- meaning, show defective artifacts which has any group id.

3. Setting the repository. You can view the defective artifacts found on specific repositories by setting the repository field. By default, it is set to All Repositories. Please note that the repository field options list only contains the repositories which have one or more defective artifacts in it. So not all the repositories you have configured in the Repositories section will show up in this list, unless of course they all contain defective artifacts.

Contents of the ReportThe Repository Health Show Report button will display a detailed list of problematic artifacts filtered according to the configuration you've set. Below is a sample Repository Health report:


You can see in the sample report that there are links to the groupId and artifactId directories of each artifact. Clicking on any of these links will bring you to the appropriate navigation page in the Repository Browse. Going back to the report, shown below the links is the specific problem or defect of the artifact. These are usually detected during repository or database scanning. The page number is also displayed on the lower left-hand part of the report.


Maven Repository Manager AdministrationThis section contains the following topics:

Snapshot Cleanup Advanced User Management Backing Up Archiva Archiva Failover

Snapshot CleanupArchiva retains an instance of a particular snapshot-versioned artifact for every successfully deployed job. When you request a snapshot artifact, the most recent snapshot is obtained. Maven examines the associated metadata in the repository to determine the correct copy to download. The Maven Repository Manager maintains each copy with a unique timestamp and build number.

For example, the contents of the repository directory for an artifact should look similar to the following:

maven-metadata.xml

test-artifact-2.1-20110928.112713-14.jar

test-artifact-2.1-20110928.112713-14.pom

test-artifact-2.1-20110924.121415-13.pom

test-artifact-2.1-20110924.121415-13.jar

The corresponding repository metadata should look similar to the following:

<?xml version="1.0" encoding="UTF-8"?>

<metadata>

<groupId>com.my.company</groupId>

<artifactId>test-artifact</artifactId>

<version>2.1-SNAPSHOT</version>

<versioning>

<snapshot>

<timestamp>20110928.112713</timestamp>

<buildNumber>14</buildNumber>

</snapshot>

<lastUpdated>20110928112718</lastUpdated>


<snapshotVersions>

<snapshotVersion>

<extension>jar</extension>

<value>2.1-20110928.112713-14</value>

<updated>20110928112713</updated>

</snapshotVersion>

<snapshotVersion>

<extension>pom</extension>

<value>2.1-20110928.112713-14</value>


</snapshotVersion>

<snapshotVersion>

<extension>jar</extension>

<value>2.1-20110924.121415-13</value>


</snapshotVersion>

<snapshotVersion>

<extension>pom</extension>

<value>2.1-20110924.121415-13</value>


</snapshotVersion>

...

</snapshotVersions>

</versioning>

</metadata>

The /metadata/versioning/snapshot element contains the information for the latest snapshot that is fetched when you request the snapshot artifact for test-artifact-2.1-SNAPSHOT. You can directly request a specific snapshot of your requirement by referencing timestamp and build numbers in your version, for example, 2.1.-20110928.112713-14.

Usually, only the latest snapshot is required for proper operation of continuous integration builds. Retention of older instances of a snapshot is helpful for


troubleshooting purposes when the continuous integration server indicates that a snapshot dependency change has broken the integration process. It is sometimes useful to pull slightly older builds from the repository, after the last working build, to identify the problem.

If no recurring cleanup operation occurs, snapshot instances can accumulate quite rapidly over the lifetime of a project. To keep storage requirements of the repository manager under control, delete older snapshots. Set options regarding retention policy according to available storage and performance requirements.

Retention Options

In a continuous integration environment, where builds are often triggered by checking in artifacts, there is the potential for a large number of builds to be executed. Each of these builds, at least the successful ones, results in some artifacts being published into the repository. These can start consuming a lot of space, and it is important to manage them.

Archiva provides two different options for automatically cleaning up old snapshots on a per-repository basis:

Repository Purge by Number of Days Older

Archiva automatically deletes snapshots older than the specified number of days. Archiva always retains the most recent snapshot, no matter how old it is.

Repository Purge by Retention Count

To use this method, you must set the purge-by-days-older value to 0. Archiva retains only the most recent snapshot instances up to this value. Older instances that exceed this count are deleted.

Deleting Released Snapshots

Once the corresponding version is released, a snapshot of that version is no longer needed. Not only does this save space, but it also ensures that your dependency references are up-to-date.

Any existing continuous integration builds that refer to the snapshot fail with a missing dependency message after the dependency is deleted from the repository manager. This failure reminds you that a dependency reference is stale and encourages you to fix the problem.

Advanced User ManagementArchiva uses Apache Redback for its user management infrastructure. To use Archiva's authentication and role management system with your organization's existing user management system, you must provide additional configuration with Redback. Redback has limited support for LDAP and other authentication systems.

Complete details are available in the following location:


http://archiva.apache.org/redback/

Backing Up ArchivaYou should provide a mechanism for backing up your Archiva file store and configuration so that you can restore it if a file system failure or corruption occurs.

The choice of backup solutions may be affected by your failover method.

Archiva FailoverAlthough Archiva does not provide a failover solution, it is important for you to maintain a failover system that stays current. Depending on your preference, you can either set up an identically configured backup system with a separate file system that is synchronized with the primary systems or configure both systems to use the same shared file system.

For more information, see the Archiva page:

https://cwiki.apache.org/ARCHIVA/high-availability-archiva.html


http://archiva.apache.org/redback/

https://cwiki.apache.org/ARCHIVA/high-availability-archiva.html

From Build Automation to Continuous IntegrationThis chapter provides a quick overview of some of the important considerations that you will need to think about when you move from a simple build automation to a continuous integration environment.

The next logical step is to move towards a continuous integration approach, so that the builds of all of your projects can be triggered, managed and monitored in one central place.

The advantage of continuous integration comes from componentization of an application and constant integration of those components as they are independently modified, often by different groups of developers. Maven projects are used to represent these components and their relationships to each other. Since Jenkins understands Maven's project relationship model, it can automatically rebuild and retest affected components in the order that they should be built in. When Jenkins detects the changes to the code-base, the affected components are built and reintegrated in correct order to ensure proper function of the entire application.

This chapter includes some of the important things to consider while moving to a continuous integration environment with Jenkins. This chapter includes the following sections:

Section 12.1, "Dependency Management" Section 12.2, "Maven Configuration to Support Continuous Integration

Deployment" Section 12.3, "Automating the Build with Jenkins" Section 12.4, "Monitoring the Build"

Dependency ManagementDependency management is a key feature of Maven and something that distinguishes it from other build automation technologies, like ANT, which Fusion Middleware has supported for some time. The section explores some important dependency management topics.

This section includes the following topics:

Section 12.1.1, "Using SNAPSHOT" Section 12.1.2, "Dependency Transitivity" Section 12.1.3, "Dependency Scope" Section 12.1.4, "Multiple Module Support"

Using SNAPSHOTSnapshot versioning is covered more extensively in Chapter 7. Using snapshots for components that are under development is required for the automated continuous integration system to work properly. Note that a fixed version, non-snapshot versioned artifact should not be modified and replaced. The best practice is that you


https://docs.oracle.com/middleware/1212/core/MAVEN/maven_version.htm#CHDCBHHF

https://docs.oracle.com/middleware/1212/core/MAVEN/ci_environmement_hudson.htm#CHDCHJHC

https://docs.oracle.com/middleware/1212/core/MAVEN/ci_environmement_hudson.htm#CHDBABIH

https://docs.oracle.com/middleware/1212/core/MAVEN/ci_environmement_hudson.htm#CHDIGGHH

https://docs.oracle.com/middleware/1212/core/MAVEN/ci_environmement_hudson.htm#CHDCEEBI

https://docs.oracle.com/middleware/1212/core/MAVEN/ci_environmement_hudson.htm#A999884





should not update artifacts after they are released. This is a core assumption of the Maven approach. However, it is worth noting that often this assumption is not correct in enterprise software development, where vendors and end users do sometimes update "finished" artifacts without changing the version number, for example through patching them in place. Even though it is possible to violate this rule, every attempt should be made to comply to ensure integration stability.

Dependency TransitivityMost projects have dependencies on other artifacts. At build time, Maven obtains these artifacts from the configured artifact repositories and use them to resolve compilation, runtime and test dependencies.

Dependencies explicitly listed in the POM may also have dependencies of their own. These are commonly referred to as transitive dependencies. Based on dependency attributes such as scope and version, Maven uses rules to determine which dependencies the build should utilize. An important part of this resolution process has to do with version conflicts. It is possible that a project may have transitive dependencies on multiple versions of the same artifact (identical groupId and artifactId). In such a case, Maven uses the nearest definition which means that it uses the version of the closest dependency to your project in the tree of dependencies. You can always guarantee a particular version by declaring it explicitly in your project's POM.

Note:

If two dependency versions are at the same depth in the dependency tree, until Maven 2.0.8 it was not defined which one would win, but since Maven 2.0.9 it is the order in the declaration that counts. Hence, the first declaration wins.

Dependency ScopeDependencies may optionally specify a scope. In addition to determining whether or not a dependency is made available to the classpath during a particular build phase, scope affects how transitive dependency is propagated to the classpath.

There are six scopes available.

Compile: This is the default scope, used if no scope is specified. Compile dependencies are available in all classpaths of a project. Furthermore, these dependencies are propagated to dependent projects.

Provided: This is much like compile, but indicates you expect the JDK or a container to provide the dependency at runtime. For example, when building a web application for the Java Enterprise Edition, you can set the dependency on the servlet API and related Java EE APIs to scope provided because the web container provides those classes. This scope is only available on the compilation and test classpath, and is not transitive.


Runtime: This scope indicates that the dependency is not required for compilation, but is for execution. It is in the runtime and test classpaths, but not the compile classpath.

Test: This scope indicates that the dependency is not required for normal use of the application, and is only available for the test compilation and execution phases.

System: This scope is similar to Provided except that you have to provide the JAR which contains it explicitly. The artifact is always available and is not looked up in a repository.

Import: (only available in Maven 2.0.9 or higher) This scope is only used on a dependency of type POM. It indicates that the specified POM should be replaced with the dependencies in that POMs. Since they are replaced, dependencies with a scope of import do not actually participate in limiting the transitivity of a dependency.

Multiple Module SupportA series of interdependent projects, such as an application, can be aggregated by a multi-module POM. This should not be confused with a parent POM which provides inherited configuration. A multi-module POM may also be an inheritance parent to sub-module projects. When a Maven build is executed upon a multi module POM, Maven examines the tree of sub-projects and calculates the correct order of dependency to build the modules.

Multiple module POMs can be useful for organizing multiple component builds in Jenkins.


Maven Configuration to Support Continuous Integration DeploymentThis section describes some aspects of Maven that you should consider while moving to a continuous integration environment.

This section contains the following topics:

Section 12.2.1, "Distribution Management" Section 12.2.2, "Snapshot Repository Settings"

Distribution ManagementEvery project that is part of continuous integration must specify a distributionManagement section in its POM. This section tells Maven where the artifacts are going to be deployed at the end of the build process, that is, which repository (local or remote). The examples used in this book use the Archiva repository. Deploying artifacts to a repository makes them available for other projects to use as dependencies.

You must define a distributionManagement section that describes which repository to deploy snapshots and releases to. It is recommended that the distributionManagementconfiguration be placed at a common inherited POM that is shared among all modules.

The following shows an example of a distributionManagement configuration:

<distributionManagement>

<repository>

<uniqueVersion>false</uniqueVersion>

<id>releases</id>

<name>Releases</name>

<url>http://server:port/archiva/repository/releases/</url>

<layout>default</layout>

</repository>

<snapshotRepository>

<uniqueVersion>true</uniqueVersion>

<id>snapshots</id>


https://docs.oracle.com/middleware/1212/core/MAVEN/ci_environmement_hudson.htm#CHDBFCIG

https://docs.oracle.com/middleware/1212/core/MAVEN/ci_environmement_hudson.htm#CHDEBBGI

<name>Snapshots</name>

<url>http://server:port/archiva/repository/snapshots</url>

<layout>default</layout>

</snapshotRepository>

</distributionManagement>

Snapshot Repository SettingsThere are some important settings that govern how and when Maven will access repositories:

Update Policy: This controls how often Maven will check with a remote repository for updates to an artifact that it already has in its local repository. Configure your snapshot repository in your settings.xml in Jenkins to use updatePolicy as always. The effect of updatePolicy is on your development systems. The default value is daily. If you want to integrate the changes as they occur in Jenkins, you should change their updatePolicy accordingly. Dependencies may change suddenly and without warning. While the continuous integration system should have sufficient tests in place to reduce the occurrence of regressions, you can still run into issues depending on up-to-the-minute snapshots while developing. One such example is the API changes.

You should get all project snapshot dependencies up-to-date so that their local build reflects the current state of the deployed code-base prior to check-in.

Server credentials: This tells Maven the credentials that are needed to access a remote repository; typically Maven repositories will require you to authenticate before you are allowed to make changes to the repository, for example, publishing a new artifact). Unless you have given the Archiva guest user global upload privileges, which is not recommended, you must specify correct credentials for the snapshot repository in the servers section. You should have a unique Jenkins user with snapshot repository upload permissions. See Chapter 4 for details about user and role configuration.

Use Maven's password encryption for the password value. The Maven guide to password encryption can be found here: http://maven.apache.org/guides/mini/guide-encryption.html.

The following shows a sample settings.xml configuration for the Jenkins user:

<settings>

...

<servers>

...


https://docs.oracle.com/middleware/1212/core/MAVEN/populating_archiva.htm#BGBDDFFC

<server>

<id>snapshots</id>

<username>Jenkins</username>

<password>{COQLCE6DU6GtcS5P=}</password>

</server>

...

</servers>

...

</settings>

Automating the Build with JenkinsThis section discusses how to set up your build jobs in Jenkins. There are various options available to build Maven projects.

Before proceeding, ensure that you have configured Jenkins, as described in Chapter 6.


Section 12.3.1, "Creating a Jenkins Job to Build a Maven Project" Section 12.3.2, "Triggering Jenkins Builds" Section 12.3.3, "Managing a Multi-Module Maven Build with Jenkins"

Creating a Jenkins Job to Build a Maven ProjectTo create a basic Maven Jenkins job:

1. Open the Jenkins web interface and log in, if necessary.

2. Create a new job:

a. Select New Job from the right-hand menu.b. Provide a unique name and select Build a free-style software project.c. Click OK.

3. Configure the source code management

Ensure that you complete configuring the Subversion server, including the SSH public and private key configuration.


https://docs.oracle.com/middleware/1212/core/MAVEN/ci_environmement_hudson.htm#CHDCACAC

https://docs.oracle.com/middleware/1212/core/MAVEN/ci_environmement_hudson.htm#CHDFBDDJ

https://docs.oracle.com/middleware/1212/core/MAVEN/ci_environmement_hudson.htm#CHDBJIHE

https://docs.oracle.com/middleware/1212/core/MAVEN/config_hudson.htm#CHDHGFFG

https://docs.oracle.com/middleware/1212/core/MAVEN/config_hudson.htm#CHDHGFFG

a. Under Source Code Management, select Subversion.b. Provide the repository URL for your project directory. For

example, svn+ssh://subversion-server/ciroot/subversion/repository/trunk/projects/my-project

Note:

In this example we are using a svn+ssh URL, which accesses Subversion using SSH. If you are using a different protocol, then the steps that are necessary to configure it may vary slightly.

Jenkins attempts to verify the URL and may respond with an error message like the following:

Unable to access svn+ssh://hostname/ciroot/subversion/repository/trunk :

svn: E200015: authentication cancelled(show details)

(Maybe you need to enter credential?)

If you get this error message, do the following:

c. From the message, click enter credentials.

d. Select SSH public key authentication (svn+ssh).

e. Enter the user name.

f. Enter the SSH private-key passphrase if required.

g. Select the private-key file from the Jenkins file system. It should be in a ~/.ssh/id_rsa format.

4. Add a Maven build step

a. Under the Build section, select Invoke Maven 3 from the Add Build Step drop-down menu.

b. Select Maven 3 home. Add necessary goals and properties in the appropriate text fields.

c. If you have a SNAPSHOT continuous integration build environment, then configure the goals to perform a clean deploy.

d. If necessary, open the Advanced settings and ensure that the Settings entry points to the Maven settings that you created in the Jenkins web interface, while configuring Jenkins.

5. Save the configuration

Click Save at the bottom of the page.

Triggering Jenkins Builds39 | w w w . b u i l d - b u s i n e s s - w e b s i t e s . c o . u k

Jenkins provides number of ways to manage a continuous integration build's triggers in Jenkins. These include manual and automated triggers. The option to manually start a build is always available for any job. When choosing an automated trigger, you may consider factors like the structure of the project, the location of the source code, the presence of any branches, and so on.


Section 12.3.2.1, "Manual Build Triggering" Section 12.3.2.2, "Subversion Repository Triggering" Section 12.3.2.3, "Schedule Based Triggering" Section 12.3.2.4, "Trigger on Jenkins Dependency Changes" Section 12.3.2.5, "Maven SNAPSHOT Changes"

Regardless of how the build is triggered, the job is added to the pending job queue and completed when the resources become available.

Manual Build Triggering

All jobs can be started from the user interface with the Build Now link.

Subversion Repository Triggering

This type of build trigger is vital to establishing a healthy continuous integration build. As changes are committed to project source, Jenkins triggers builds of the associated Jenkins jobs. The trigger does this by periodically checking the associated Subversion URL for changes.

To enable this trigger, select the Poll SCM option. You must then provide a cron expression to determine the schedule Jenkins uses to poll the repository.

Schedule Based Triggering

For some job types, you can trigger them on a schedule. Long running system integration tests are an example of a build that you might want to run periodically as opposed to every time the test source is modified.

Schedule based triggers are configured with cron expressions exactly like the Poll SCM trigger.

Trigger on Jenkins Dependency Changes

Trivial projects may contain multiple builds that produce unique artifacts that have dependencies on each other. If Jenkins rebuilds an artifact as the result of any trigger type, it must also build and test dependent artifacts to ensure integration is still valid. When dependencies that are also built on this Jenkins server are successfully completed, Jenkins recognizes these relationships automatically and triggers the build. In order for this trigger to work, the dependencies must also enable the post-build action Notify that Maven dependencies have been updated by Maven 3 integration.

Maven SNAPSHOT Changes


https://docs.oracle.com/middleware/1212/core/MAVEN/ci_environmement_hudson.htm#CHDHGEAA

https://docs.oracle.com/middleware/1212/core/MAVEN/ci_environmement_hudson.htm#CHDJBEFE

https://docs.oracle.com/middleware/1212/core/MAVEN/ci_environmement_hudson.htm#CHDHFFFI

https://docs.oracle.com/middleware/1212/core/MAVEN/ci_environmement_hudson.htm#CHDHAFJA

https://docs.oracle.com/middleware/1212/core/MAVEN/ci_environmement_hudson.htm#CHDEIGAG

If there are dependencies that are undergoing concurrent development and being managed as snapshots in your common Maven repository, then they should be managed by your Jenkins instance. If this is not practical, then you can use the SNAPSHOT dependency trigger to monitor the Maven repository for changes in such dependencies. When an updated SNAPSHOT dependency has been detected, the build will trigger and download the new dependency for integration.

This trigger also uses a cron expression to configure the polling interval.

Managing a Multi-Module Maven Build with JenkinsTo manage your build dependencies correctly, you may add each project as a separate Jenkins build and configure the dependency triggers manually, or you can configure a multi-module Maven POM as a parent Jenkins job. The multi-module solution reduces the possibility of making mistakes wiring the dependencies manually. It also automatically stays up-to-date as the dependencies are changed in the Maven configuration.

Configuration of a multi-module build is identical to configuration for regular projects. To examine the results of component project builds, Jenkins provides a tab in the build results page in the Maven 3 Build Information link. At the top of the page, the Modules tab summarizes the component build results.

To examine the log for any of the sub-project builds, use the Console Log link. All project and sub-project builds are logged in their sequence of execution.


Monitoring the BuildJenkins should be configured to send notifications to the correct parties when the build breaks. The continuous integration system must ensure that their changes do not break the build and test process. If this does happen, they need to be notified of the breakage and must address the issue as soon as possible. Jenkins should have each user registered as a unique user. The Jenkins user name must match the Subversion user name that they ordinarily commit under. Jenkins relies on this name to look up the proper contact email to send notification to.

General email notification configuration can be found under Manage Jenkins -> Configure System -> E-mail Notification.

You must also make sure some form of user management is enabled. You can do this by selecting Enable Security from the Configure System panel. There are a number of choices for user management and additional third-party plug-ins to support most other popular solutions, such as LDAP. The best option is to use Jenkins's own user database. Select this choice from the Access Control section. There are additional options for limiting permissions to particular users and groups.

To add a new user, the user simply needs to follow the sign up link at the top of the Jenkins home page and fill out the necessary information. The user name must match the corresponding Subversion user name.

Following Up on the Triggered BuildsNormally, automated notification is sufficient to ensure the continuous build system is kept healthy and produces effective results. However, there are conditions that can require additional monitoring and coordination to get the system back to an operational state. It is a good policy to designate a build coordinator to track down such problems, coordinate solutions for broad problems and perform troubleshooting when the system itself is suspect.


Archiva release process1.Post to the dev list a few days before you plan to do an Archiva release2.Recreate the staging repository on archiva-repository.apache.org - make sure that it is

not scanned (so that .index* is not created). Your maven setting must contains the entry to be able to deploy.

3. <server>

4. <id>archiva-repository.releases</id>

5. <username></username>

6. <password></password>

</server>

7.If there are changes in the parent pom, release parent pom – https://svn.apache.org/repos/asf/archiva/parento mvn release:prepare (verify that it has been properly tagged)o mvn release:perform (verify that it has been deployed correctly in the staging repo)

8.Update the parent pom version of archiva – https://svn.apache.org/repos/asf/archiva/trunko change the parent pom version to the archiva-parent version that has just been

releasedo commit the changes made

9.Update the release notes and the site.xml for version changes in archiva-docs10. Verify that the webapp-tests are building successfully. Since it is in a separate profile

but inside the Archiva source tree, it will not be released but will still be included in the release tag. If some tests are failing, comment it out first so that only the passing tests are executed when the webapp-tests module are built from the tag.

11. Release archiva You should have a GPG agent running (preferred), and confirm it works by running "gpg -ab" (type some text and press Ctrl-D). If you do not have a GPG agent running, make sure that you have the "apache-release" profile set in your settings.xml as shown below.

12.<profile>

13. <id>apache-release</id>

14. <properties>

15. <gpg.passphrase>[GPG_PASSWORD]</gpg.passphrase>

16. </properties>


</profile>

Set your user credentials for the stage repo in the servers section of your settings.xml for archiva-repository.releases.

Execute mvn release:prepare (check that it has been properly tagged. the tag name must be.. archiva-[VERSION]).

Next, execute mvn release:perform

Download the uploaded files via wget:

ex.

wget http://archiva-repository.apache.org/archiva/repository/staged-releases/org/apache/archiva/archiva-jetty/1.3/archiva-jetty-1.3-bin.tar.gz

Verify the signatures:

ex.

gpg -v archiva-jetty-1.3-bin.zip.asc

The documentation is deployed as part of the process to the final location for review in the vote: http://archiva.apache.org/docs/1.3/. If the vote doesn't pass, the documentation will need to be removed from the server for redeployment. Commit the sources and binaries from org/apache/archiva/archiva-jetty, and org/apache/archiva/archiva to the svn distribution tree. First in dev tree: https://dist.apache.org/repos/dist/dev/archiva/ (if the vote pass they will be copied to release tree) https://dist.apache.org/repos/dist/release/archiva

svn co https://dist.apache.org/repos/dist/dev/archiva/ archiva-dev-release

cd archiva-dev-release

sh ./release-script-svn.sh VERSION STAGING_URL

Call for a vote in the dev list and wait for 72 hrs. for the vote results. 3 binding votes are necessary for the release to be finalized. example If the vote fails or needs to be canceled, the version number should not be re-used if the version was made available for public download. After the vote has passed, move the files from


dist dev to dist release: svn mv https://dist.apache.org/repos/dist/dev/archiva/ to https://dist.apache.org/repos/dist/relase/archiva/ To sync the jars to ibiblio, execute:

NOTE: the stage plugin doesn't work with maven3 you must use maven 2.2.1

mvn stage:copy -Dsource="https://archiva-repository.apache.org/archiva/repository/archiva-releases-stage/"

-Dtarget="scp://[APACHE_USERNAME]@people.apache.org/www/people.apache.org/repo/m2-ibiblio-rsync-repository"

-Dversion=1.3 -DrepositoryId=apache.releases

mark the appropriate release version in JIRA as complete Update the archiva site (https://svn.apache.org/repos/asf/archiva/site/) for the versions and release notes URL and run mvn site-deploy. The 3 properties to change are at the bottom of pom.xml before generating the site. Once mirroring done (can be 24H): remove previous versions from https://dist.apache.org/repos/dist/release/archiva/

Publish the reference docs (sh ./deploySite.sh in the archiva-modules directory) from the release tag. You may have to exclude the archiva-webapp module to do this, and will require MAVEN_OPTS=-Xmx256m. You may need to use Maven 2.2.1 instead of Maven 3.x for this.

Send out an announcement of the release to:

o [email protected] [email protected] [email protected]


BrowsingPermissionsThe user can only browse those repositories where the user is an observer or a manager. If the user does not have permission to access any repository, a message saying "You have access to no repositories. Ask your system administrator for access" will be displayed.

Repository Browse LayoutThe current layout of the repositories in Repository Browse uses the Maven 2 layout, which is the groupId, artifactId and version. When the version is clicked, the Artifact Info page (see the next section) will be displayed. There is currently an issue with regard to Maven 1 artifacts, see http://jira.codehaus.org/browse/MRM-585.

Artifact InfoItems in the repositories are hyperlinked allowing you easy access to view more information. By clicking on the Group ID or Artifact ID you will be taken to the repository browser. The Artifact Info page is divided into six views:

1. Info. Basic information about the artifact is displayed here. These are the groupId, artifactId, version and packaging. A dependency pom snippet is also available, which a user can just copy and paste in a pom file to declare the artifact as a dependency of the project.


http://jira.codehaus.org/browse/MRM-585

2. Dependencies. The dependencies of the artifact will be listed here. The user can easily navigate to a specific dependency by clicking on the groupId, artifactId, or version link. The scope of the dependency is also shown.

3. Dependency Tree. The dependencies of the artifact are displayed in a tree-like view, which can also be navigated.


4. Used By. Lists all the artifacts in the repository which use this artifact.

5. Mailing Lists. The project mailing lists available in the artifact's pom are displayed here.


6. Download. Clicking on this link will download the artifact to your local machine.

7. View Artifact Content. Clicking on this link to view artifact content remotely

Downloading ArtifactsArtifacts can be downloaded from the artifact info page. All files, except for the metadata.xml files, that are associated with the artifact are available in the download box. The size of the files in bytes are displayed at the right section of the download box.

Note: Upon downloading the artifact, you will be asked to enter your username and password for the repository where the artifact will be downloaded from. Only users with Global Repository Manager, Repository Manager, or Repository Observer roles for that repository can download the artifact.

Metadata


In 1.4, the new repository API or "metadata repository" was introduced. One of the essential features of the metadata repository is to be able to add generic information (such as ratings, comments, etc.) about a project through facets. These facets are stored in the project properties file in the metadata repository.

Only users with Repository Manager roles for the repository where the artifact is located can add or delete properties in the metadata via the Metadata tab in Artifact Browse.

To add a property in the metadata, just specify a Property Name and a Property Value in the respective text fields then click Add.

To delete a property, just click the corresponding delete icon (X) of the specific property you want to delete. A "Property successfully deleted." message should be displayed after a successful delete.


SearchingThe Search functionality of Archiva allows a user to search for specific artifact references in the repository.

IndexingBefore artifacts can be searched in Archiva, they need to be indexed first. Aritfacts are indexed during these instances:

when a repository is scanned when an artifact is deployed or uploaded in the repository when an artifact is proxied or downloaded from a remote repository when remote index is available and downloaded

During repository scanning, the index-content consumer (see Consumers) creates an indexing task and queues it in an indexing task queue. This indexing task is in turn executed by a task executor and that's where the actual indexing happens. A similar indexing task is also created and queued as artifacts are deployed in the Archiva repository or proxied from a remote repository. The reason behind this is to avoid multiple or simultaneous update of the index (a repository scan might be executing while artifacts are being deployed in the repository). Note:This behavior applies for versions starting 1.2.1.

What Can Be Searched?The repository files that are indexed during repository scan can be configured in the Repository Scanning page, in the Repository Scanning - File Types section (indexable-content). By default, the indexable-content file types are:

**/*.txt

**/*.TXT

**/*.block

**/*.config

**/*.pom

**/*.xml

**/*.xsd

**/*.dtd

**/*.tld

Quick Search


The contents of all the files in the repository that matches the above configuration will be indexed during repository scan. So when you type a word in the search box, Archiva will search the index for that query string and return all the search hits in the form of a paginated list of artifacts. For example you typed in 'ant', the search result would contain the list of artifacts that use or reference 'ant'.

For query strings containing whitespaces, Archiva searches for the query string including the whitespaces. So if you typed in 'commons logging', the search result would contain the list of artifacts that reference 'commons logging' which is still separated by whitespace. In this case, 'commons-logging' (hyphen separated) is not included in the search results.

Archiva can also search the index for java classes, packages, and methods and return a list of artifacts containing the query string. In the previous versions, we need to append the keyword 'bytecode:' before the query string in the search box (like 'bytecode:myMethod'). But since version 1.2, we no longer need to type the keyword. Just type the java class or package name in the search box.. and voila!

You can use various criterias to search artifacts:

Simple Query string

Advanced Paramters


OSGI Parameters


Search resultsYou can apply various filters on the search results.

Below is a sample screenshot of the search results:


When the user clicks a specific artifact in the search results list, Archiva will direct the user in the Artifact Info page (the same page from the Repository Browse). Otherwise if it is not a pom file (ex. metadata.xml), the file will appear as a file to be downloaded from the browser.

SecurityThe Search functionality respects the repository permissions. If the user is not logged in to Archiva and does a search, only those repositories with guest permissions will be searched for the query string. And if the user is logged in to Archiva and does a search, only those repositories in which that user has permission to access will be searched for the query string.


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 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 ArchivaIf 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/repository/internal/</url>

<mirrorOf>external:*</mirrorOf>

</mirror>

</mirrors>


</settings>

Note: There are other controls you can use on what is mirrored. See Maven's Guide to Mirror Settings for more information.

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/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 repositoryYou 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

2.<settings>

3. 

4. <profiles>

5. <profile>

6. <id>Repository Proxy</id>

7. <activation>

8. <activeByDefault>true</activeByDefault>

9. </activation>

10. 

11. 

12. 

13. <repositories>

14. <repository>


16. </repository>


18. </repositories>

19. 

20. 

21. 

22. <pluginRepositories>

23. <pluginRepository>


25. </pluginRepository>


27. </pluginRepositories>

28. </profile>


30. </profiles>


</settings>

32. 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/repository/internal/</url>

<releases>

<enabled>true</enabled>

</releases>

<snapshots>

<enabled>false</enabled>

</snapshots>

</repository>

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


Deploying to RepositoryThere are different ways on how you can deploy artifacts in an Archiva repository.

Maven Configuring Maven to deploy to an Archiva repository Web UI Deploying via the Web UI Form

Starting with Archiva 1.2.3, it is possible to block re-deployment of released artifacts to a specific repository. This can be configured through the repository configuration page by ticking theBlock Re-deployment of Released Artifacts checkbox.

WARNING The deployed artifact may not appear immediately in the search results. The execution of the index-content repository consumer and other scanning consumers are queued for execution to prevent concurrent updates to the index.

Configuring Maven to deploy to an Archiva repository1. Create a user in Archiva to use for deployment (or use guest if you wish to deploy without a

username and password)2. The deployment user needs the Role 'Repository Manager' for each repository that you want

to deploy to3. Define the server for deployment inside your 'settings.xml', use the newly created user for

authentication4. <settings>


6. <servers>

7. <server>

8. <id>archiva.internal</id>

9. <username>{archiva-deployment-user}</username>

10. <password>{archiva-deployment-pwd}</password>

11. </server>

12. <server>

13. <id>archiva.snapshots</id>

14. <username>{archiva-deployment-user}</username>

15. <password>{archiva-deployment-pwd}</password>

16. </server>



18. </servers>


</settings>

Deploying to Archiva using HTTPConfigure the distributionManagement part of your pom.xml (customising the URLs as needed). The id of the repository in distributionManagement must match the id of the server element in settings.xml.

<project>


<distributionManagement>

<repository>

<id>archiva.internal</id>

<name>Internal Release Repository</name>

<url>http://reposerver.mycompany.com:8080/repository/internal/</url>

</repository>

<snapshotRepository>

<id>archiva.snapshots</id>

<name>Internal Snapshot Repository</name>

<url>http://reposerver.mycompany.com:8080/repository/snapshots/</url>

</snapshotRepository>

</distributionManagement>


</project>

Deploying to Archiva using WebDAVIn some cases, you may want to use WebDAV to deploy instead of HTTP. If you find this is necessary, follow the same process as for HTTP, with these additional steps:

1. Add dav: to the front of the deployment URLs:2. <project>


4. <distributionManagement>

5. <repository>

6. <id>archiva.internal</id>


7. <name>Internal Release Repository</name>

8. <url>dav:http://reposerver.mycompany.com:8080/repository/internal/</url>

9. </repository>

10. <snapshotRepository>

11. <id>archiva.snapshots</id>

12. <name>Internal Snapshot Repository</name>

13. <url>dav:http://reposerver.mycompany.com:8080/repository/snapshots/</url>

14. </snapshotRepository>

15. </distributionManagement>


</project>

17. Add a build extension to your pom.xml (not required in Maven 2.0.9 and above)18. <project>


20. <build>

21. <extensions>

22. <extension>

23. <groupId>org.apache.maven.wagon</groupId>

24. <artifactId>wagon-webdav-jackrabbit</artifactId>

25. <version>2.2</version>

26. </extension>

27. </extensions>

28. </build>


</project>

Deploying using other protocolsYou can also deploy to the Archiva server using traditional means such as SCP, FTP, etc. For more information on these deployment techniques, refer to the Maven documentation.


Once the files are deployed into the location of the Archiva managed repository, they should appear in the Browse page. The artifacts should also be searcheable as long as the index-content repository consumer is enabled.

Deploying Third-Party Artifacts to Archiva using MavenYou can use mvn deploy:deploy-file to deploy single artifacts to Archiva. Once you have the settings file in place as described above, you can deploy the artifact using this type of command:

mvn deploy:deploy-file -Dfile=filename.jar -DpomFile=filename.pom

-DrepositoryId=archiva.internal

-Durl=http://repo.mycompany.com:8080/repository/internal/

For more information, consult the documentation for the deploy:deploy-file goal

If you wish to use WebDAV to deploy the file, add dav: to the start of the URL as in the previous instructions.

However, on versions of Maven prior to 2.0.9, you will also need to create a file called pom.xml in the directory from which you intend to execute "mvn deploy:deploy-file":

<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-jackrabbit</artifactId>

<version>2.2</version>

</extension>

</extensions>

</build>

</project>


This pom will not be deployed with the artifact, it simply serves to make the WebDAV protocol available to the build process.

Alternately, you can save this file somewhere else, and use "mvn ... -f /path/to/filename" to force the use of an alternate POM file.

Deploying via the Web UI FormThe easiest way to deploy in the repository is via the Web UI form, which can be accessed in the Upload Artifact section. Just follow these steps:

1. In Archiva, click the Upload Artifact option in the left menu. You should see a form similar to the one at the end of this section.

2. Fill in the following required fields: Group Id - the groupId of the artifact to be deployed. Artifact Id - the artifactId of the artifact to be deployed. Version - the version of the artifact to be deployed. Packaging - the packaging of the artifact to be deployed. (ex. jar, war, ear, etc.) Drag and drop files to be deployed.

3. Select the repository you want to deploy to. Please note that if you do not have write permission to the repository, you will not be allowed to deploy on it.

4. Now, if you want Archiva to generate a pom for the artifact, check the Generate Maven 2 POM field. (Right now, only Maven 2 poms can be generated.) Alternately, supply a POM file to be deployed alongside the artifact.

5. Click Saves files and a message will be displayed notifying you if the upload/deployment was successful or not.

These are the files that will be in your repository after deployment:

artifact POM file (if you supplied one or checked Generate Maven 2 POM) maven-metadata.xml (this will be created if none exists in the artifact level yet, otherwise it

will just be updated) maven-metadata.xml.sha1 and maven-metadata.xml.md5 (these will be generated for newly

created maven-metadata.xml files, otherwise they will just be updated)


Querying ArtifactsSometimes you only need to download artifacts using a query and via the command line

Query format wget "http://localhost:9091/archiva/restServices/archivaServices/searchService/artifact?g=org.apache.archiva&a=archiva-model&v=LATEST"

Query parameters:

g= groupId (mandatory) a= artifactId (mandatory) v= the version (or LATEST keyword) (mandatory) r= the repository (optional, if none all repositories available for reading for the current user

are searched)

NOTE: the response is a redirect (so you need to follow redirect if you want to download the artifact). No content response is returned if the query doesn't match any artifact.


Understanding Apache Archiva Security RolesArchiva uses the Redback security framework for managing repository security. When the server is first started, you will be prompted to create an administration user. This user will be given permission to administer all aspects of the system (as well as access to all of the repositories). This user can then be used to grant permissions to other users.

A guest user is also created by default, and given read access to the default repositories (internal and snapshots). Repositories with guest user access can be accessed without the use of a username and password (or without being logged in to the web interface).

However, when new repositories are created, by default no permissions are assigned and only the administrators will have access until it is explicitly granted.

Note that Redback has the concept of inferred roles, so the assignment of some roles will imply other roles (which will be displayed in the web interface).

Repository RolesArchiva contains the following roles for repository access:

Repository Observer: users with this role can read from the given repository that the role is for (including access through the browse and search features of the web interface)

Repository Manager: users with this role can write to and administer the given repository that the role is for

Global Repository Observer: users with this role can read from any repository (including access through the browse and search features of the web interface)

Global Repository Manager: users with this role can write to and administer any repository in the instance

Roles list


Role details

Attach users to a role


General RolesArchiva also contains the following general roles for security of the instance:

System Administrator: full access to all functionality in the system User Administrator: ability to create, edit, and grant roles to other users in the system

The guest and registered user roles do not affect repository access.


apache archiva user guide - build business websites web...

Documents