Proximity Quick start

This document will describe how to setup Proximity quickly. It does assume you have some basic knowledge about your OS and Java and you already have Java on your machine.

Since there is a Demo site with live instance of latest Proximity, these images shown here will not be updated so often as before, so the image and the "real" application may show some differences.

The setup of Apache Tomcat 5 used in this example will not be show. This document simply assumes that you have downloaded and installed Tomcat (this doc used Tomcat 5.5.17). If not, please go to Apache Tomcat site and download it. Anyway, since this WAR file is simple J2EE webapp and have no whatsoever dependency on Tomcat, you can try it on any J2EE compliant Servlet container too.

The screenshots shown here were taken after installation of the downloaded WAR file and just placed it into $TOMCAT_HOME/webapps directory for automatic deployment. Some advanced users may unzip the WAR file and deploy it automatically to customize the deployment (two most interesting files are /WEB-INF/proximity.properties and /WEB-INF/applicationContext.xml).

Let's take a short tour...

Proximity is up, showing default page.

The second page is the Search page. On this page we can search amongst downloaded artifacts. There a "simple" search and Lucene Query search. The simple search searches on index searching for items that has names that starts with the search input.

The Lucene query search is more powerful. The interesting thing is the search engine is extensible. Currently, the MavenAwareLuceneIndexer parses the POM and extracts various interesting infos from it. Searchable keywords are listed on page with some samples. Here, we sarched with Lucene Query for "kind:pom".

Next, Proximity on Repositories page shows the list of configured repositories. Repositories that have localStorage will be shown with their directories. Proxy repositories will be shown together with their remoteUrl parameter and localStorage directory path. The WAR default behaviour is to create storages on Java System Propery "user.home" appended with "proximity".

This page should became more interesting from the moment when runtime Repository configuration becomes possible (scheduled for later releases).

Proximity collects statistics during runtime (if configured so). Initially statistics page will be empty, since no activity happend on Proximity. Currently Proximity just collects simple stats. As you see, various info about requests and requested artifacts are logged.

Proximity have a maintenance page. This page currently holds only the reindexing tool. Reindexing is possible to whole Proximity (all registered repositories) and targeted at some chosen repository.

And finally, we have the repository browsing function. Notice how Proximity differentiates between repositories? You can also filter to them and sort artifacts... Also, there is the group column, which indicates which repositories will be aggregated.

Also, notice the cool but useful feature: leave the mouse over the artifact or directory link, and you will know about as much as Proximity does! The indexed properties keys are searchable on Search page! Here is it:

A single line shows: kind icon, item name, link to project's home (if POM contains it), link to it's original location (eg. link to central), item deletion (uninmplemented), size, date, repository group and repository:

Proximity shows which folders are proxied (network icon) and which are hosted:

A new view is the Artifact browsing function. It simply leads in groupId, artifactId, version namespace:

Using it with Maven2

To use Proximity with Maven2, you have to make a few simple steps. A working copy of Proximity is assumed. Also, installed and working Maven2 is also assumed. Go to Apache Maven to get infos how to setup Maven2.

First, you need a settings.xml file to instruct Maven to use Proximity as a mirror of central repo. Mirror, not http proxy!

Below, we see the minimal file to achieve this, below is a code to copy+paste.

<settings>
  <mirrors>
    <mirror>
      <id>Proximity</id>
      <mirrorOf>central</mirrorOf>
      <name>Proxmity mirrored central.</name>
      <url>http://localhost:8080/px-webapp/repository</url>
    </mirror>
  </mirrors>
</settings>

Using this minimal snippet settings as is, the Maven2 will use Proximity instead of direct access to central repository.

Place this snippet into a file called settings.xml located in $HOME/.m2 directory. You may have to create ".m2" directory if you had never executed Maven2! For example:

• on Windows, %HOME% defaults to C:\Documents and Settings[USERNAME]. To recheck it, open a cmd.exe and type "cd %HOME%". The current directory will be your home directory.
• on Unix/Linux, $HOME defaults to /home/[USERNAME].

Next, we can use Maven2 and build. Notice the download URLs!

Notice the URLs from where downloads Maven2 now. Also, you will see a slight change in behaviour of Maven2: the download counter will appear as not working. This is due fact, that Maven2 issues a HTTP GET command to Proximity, it does what it should (eventually accessing remote site and download requested item) and then as a response "quickly" hand the requested artifact to Maven2.

To finish this long story, here is a sample "benchmark": First, we built with empty local repository and fresh Proximity installation. We built -- of course -- the Proximity itself :)

Next, we deleted the local repository, and built again using the same running instance of Proximity.

Wow. 45 seconds alright. But where the hell is 12 minutes?!?!?

Have fun!