Roles and permissions
In preparation for the latter sections of this article, let's familiarize ourselves with the user roles and permissions available in Archiva. The list of available roles can be seen by clicking a user account in User Management and then clicking on the Edit Roles link.
Some of the roles in Archiva are resource-based with each repository treated as a resource. This means that access is controlled at the repository level.
There are eight types of roles available in Archiva. They are:
- System Administrator: Provides access to Manage and Administration sections, user administration privileges, and read and write permissions to all repositories.
- User Administrator: Provides access to User Management and User Roles pages.
- Global Repository Manager: Provides read and write permissions to all repositories.
- Global Repository Observer: Provides read permission to all repositories.
- Repository Manager (resource level): Provides read and write permissions to a given repository.
- Repository Observer (resource level): Provides read permission to a given repository.
- Registered User: The default role assigned to a user who has registered in Archiva.
- Guest: Provides the same permissions that are enabled for the built-in guest user account, which we will discuss later on.
A user assigned with a Global Repository Manager or resource level Repository Manager role automatically gains the Global Repository Observer or resource level Repository Observer role respectively.
Users assigned with a Repository Manager role should be able to access the Find section as well as Upload Artifact and Delete Artifact menu in the web application. On the other hand, users with a Repository Observer role should only be able to access the Find section. Repository-level security applies to each corresponding operation. This means that a user will only be able to search, browse, and upload to or delete artifacts from those repositories that they have permission to access.
When managing roles and permissions, another thing to take note of is the guest account. To enable access without authentication for a specific resource or operation, just assign the guest user the appropriate role. By default, the guest user is already assigned the Repository Observer role for internal and snapshots repositories. This allows anyone to be able to browse and search for artifacts from these repositories. If you edit the guest user account, you should be able to see the following configuration:
As you can see the guest user doesn't yet have read access to the releases repository. In our examples, we will assume that the repository will be available to everyone that can access Archiva. So to make this consistent with the snapshots repository, check the Repository Observer box for releases and submit the form.
You can see for yourself how the guest account works by logging out of Archiva and clicking Browse on the navigation menu. The artifacts that were requested and were downloaded to our proxy repository should be visible in the Browse page, similar to what is seen in the following screenshot:
As we work through the rest of the article, we will cover a few more things about access control in Archiva. Now that we are familiar with the security basics, we are ready to tackle some of the more advanced features of Archiva.
In the next section, we will learn techniques for configuring our Archiva repositories.
Introducing repository groups
In Archiva 1.1, the concept of repository groups (also known as virtual repositories) was introduced. Taking the meaning of the term virtual literally, these repositories are physically non-existent repositories. A virtual repository is simply a URL which gives a single interface to a group of managed repositories.
Let's visualize this with a simple scenario. For example, we have a Maven 2 project which has dependencies on artifacts that reside in multiple repositories. In this case, we will assume that we have a nearby proxy cache configured in Archiva for each of them. Given this scenario, it would mean that we have to configure each of these repositories in our settings.xml (or POM), in order for us to get the needed artifacts and to be able to build our project. If these repositories are secured, we also need to configure our credentials for each. This leaves us with a long (and possibly messy) settings.xml. Remember, a messy configuration is an attraction for errors.
To avoid this problem, we can make use of repository groups in Archiva. We can create a repository group and configure or add multiple repositories under that group. So when an artifact request is made (for example, by Maven) using the repository group URL, the repositories underneath it will be searched until the requested artifact is found and returned to the client.
The following section teaches us how to configure repository groups and experience their strength first-hand.
Configuring and using repository groups
Before jumping into configuration, it is good to see how it will be without the aid of repository groups. As the Centrepoint project refers to the released version—POM Apache Maven 2: Effective Implementations Book, anyone who builds that project must be able to get the organization POM from the releases repository. This is a perfect setup for using repository groups. Let's begin by wiping out our local repository again and building the Centrepoint project.
centrepoint$ mvn clean install
The build should fail with the following error:
[INFO] Scanning for projects...
[ERROR] FATAL ERROR
[INFO] Failed to resolve artifact.
Reason: Unable to download the artifact from any repository
from the specified remote repositories:
Our organization POM cannot be found because it resides in the Archiva releases repository, and we don't have it configured in our settings.xml. The version in ../effectivemaven-parent/pom.xml is also not used because the versions now differ. To get past this problem, we must add the following configuration in the settings.xml:
<name>Archiva Managed Releases Repository</name>
We already configured the <server> credentials for the releases repository when we tried deploying to Archiva using Maven so we no longer need to configure that.
If you try building Centrepoint again, the build will still fail. Notice that Maven didn't even seem to try looking for the artifact from the releases repository we added previously. This is because we have locked down Maven to use only the local mirror repository internal. This is the effect of the <mirrorOf>*</mirrorOf> configuration in our settings.xml, Staying in Control with Archiva. Just change it to <mirrorOf>*,!releases</mirrorOf> so that Maven would respect the additional repositories.
Execute the build again. This time we should be able to get a successful build.
However, for every member of the team working on the Centrepoint project, the settings.xml (now over 40 lines long) is needed at the minimum. As the project grows bigger, more artifacts are added. Also, if these new artifacts are located in other repositories, you would need to add this repository to your settings.xml and so on and so forth.
We already learned at the start of this section that in situations such as this, a repository group can make things easier for us developers. Let us see how we can create one.
Let's go back to our running Archiva instance. Click Repository Groups, then type public in the Identifier field on the upper right-hand corner of the page and click Add Group. We now have a virtual repository named public with the following URL: http://localhost:8081/archiva/repository/public.
You may change the name of the repository group to a more appropriate one if the repositories are not really for public consumption.
To add managed repositories under the group, just select the repository you would like to add from the list under the created group and click Add Repository. Add the releases and internal repositories (this order is used so that requests for the organization's artifacts are never made on external proxied repositories). Note that we don't want to add the snapshots repository to the group as that might change the behavior of the repository. One example of this is when dealing with version ranges. You might end up getting a snapshot version instead of a released version.
Now, with this configuration, we are telling Archiva that if an artifact request is made on the repository group public, it should look for the artifact in these two repositories (based on the order they are listed) and return the first matching artifact it sees.
You can change the ordering of the repositories to be searched by moving a repository up or down the repository group configuration via the Up and Down icons.
After configuration, the page should look similar to the following:
Now that we have a repository group that we can use, let's configure it in our settings.xml. Remove the profile we added previously, and adjust the mirror section as follows:
Notice how much shorter and simpler our settings.xml is now.
The guest user has access to all of the repositories in the group so we don't need a corresponding <server> for the mirror. However, if read access control applies to any repositories in the group, make sure to add a <server> for the ID of the mirror (not the underlying repositories that are no longer visible to Maven). The existing <server> definitions continue to be used for deployment, as deployment cannot be done to a group.
Let's try building Centrepoint again, but this time with a clean local repository, using the new settings.xml. We should be able to see both com.effectivemaven: effectivemaven-parent:pom:1 and the other dependencies from the central repository being retrieved from our public repository group, ending with a successful build as follows:
[INFO] Scanning for projects...
[INFO] Reactor build order:
[INFO] Building Centrepoint
[INFO] task-segment: [clean, install]
What else can we do with repository groups? Consider, for example, that we added new dependencies to our Centrepoint project and these dependencies are projects being worked on by another team within the company. Let's say the other team have their own deployment repository (separate from ours) managed by Archiva as well. We no longer have need to make any changes in our settings.xml (or POM). The repository just needs to be added in the public repository group and the appropriate permissions assigned to the Centrepoint project developers' accounts.
Configuration is much simpler now and is concentrated in Archiva itself. Developers and team members won't have to configure their settings.xml each time a new repository is needed.
RSS feeds—discovering new artifacts in your repository
RSS has become the de facto standard with regard to news feeds and updates on the web. The Archiva community has seen how the project can take advantage of this current trend by providing RSS feeds for new artifacts in the repository. Projects that use or depend on specific libraries would be able to know when a new release is available or when there is a new build. This is especially useful when a project is dependent on a fix that would be available in the next release or in the next build.
A Repository Observer role is required at least in order to subscribe to a feed in Archiva.
There are two levels of RSS feeds available in Archiva: repository level and artifact level. In the following sections, we will be using Thunderbird's RSS feed reader for demonstration purposes. You can get Thunderbird from http://www.mozillamessaging.com/en-US/thunderbird/ and can set it up using the installation guides at http://www.mozillamessaging.com/en-US/support/. You can also use other RSS feed readers such as Google Reader. If access to your repositories require authentication, your feed reader must support authentication. If security is lenient, you can just disable authentication for read operations to your repository by granting the guest account the Repository Observer role.
Repository level feeds
Repository level feeds notify subscribed users of new artifacts found in the repository. To subscribe to a repository level feed, first go to http://localhost:8081/archiva/admin/repositories.action (Repositories page).
Unfortunately, at the time of writing, only system administrators are able to access this page so you must log in to Archiva using the admin account.
From this page, you can right-click on the RSS feed icon on the upper righthand corner of repository snapshots configuration and copy the link location.
If you have not created an account for your RSS feeds in Thunderbird, go to File | New | Account... in the top menu. Select RSS News & Blogs then click Next. Use the default Account Name "News & Blogs", click the Next button then Finish. A folder with the same name as the Account Name should appear on the left pane, similar to the one in the following screenshot:
Under the RSS News & Blogs link seen in the previous screenshot, click Manage subscriptions. Add a new RSS subscription for the snapshots repository by pasting the URL we copied in step two into the Feed URL field.
The feed subscription to the snapshots repository should immediately appear under the News & Blogs folder. Clicking on the feed should yield something similar to the following:
Notice that the feed in the previous screenshot shows the subject line New Artifacts in Repository 'snapshots' as of Sat Aug 08 12:48:27 PHT 2009. The date corresponds to the date and time of an execution of the repository scan. It is during this scanning when new artifacts in the repository are discovered. When the reader updates or checks for new feeds, Archiva gets all the new artifacts found (if there are any) during each execution of the repository scanner and sends them back as multiple entries to the feed reader.
Artifact level feeds
In contrast to repository level feeds, artifact level feeds notify subscribed users of new versions of a specific artifact deployed or discovered in the repository. You can use this if you want finer grained notifications or if you are interested only in a specific artifact. This is useful when you're waiting for certain project dependencies to be released as it can provide you immediate notification once the release is available in the repository. You can also use this to be notified of newly deployed builds for purposes such as QA testing or simply for development.
Now, let's say we want to know when there are new builds of the Centrepoint distribution available.
This time we start by logging in to Archiva and going to the Browse page.
Click on the group com.effectivemaven.centrepoint to view the artifacts under the group. You should see the different Centrepoint projects listed, each with a corresponding RSS feed icon beside it:
Again we can right-click the RSS feed icon next to distribution and copy the link location.
Finally, we go back to Thunderbird and add it as a new feed under News & Blogs, the same way we added the feed for the snapshots repository earlier. Check that the feed URL you copied is: http://localhost:8081/archiva/feeds/com.effectivemaven.centrepoint/distribution. The artifact path in the URL distinguishes this feed from the repository feed.
After the feed is added in Thunderbird, clicking on the feed should display text identical to the following:
Similar to the behavior of repository level feeds, when the reader updates or checks for new feeds, information about newly found versions of the artifact in the Archiva repositories will be sent back to the feed reader.
Let's try deploying a new snapshot of Centrepoint Distribution. Go to your local checkout of Centrepoint and execute the following from the command-line:
centrepoint$ mvn clean deploy
After the project is deployed, go back to Thunderbird and force it to update the feed for Centrepoint Distribution. You should see a new entry appear in its corresponding folder.
So far, with Archiva, all we have been talking about is the end-user functionality like deploying and discovering new artifacts in the repositories. The next sections discuss the other side of the spectrum—the administrator functionality.
If you have read this article you may be interested to view :