Tuesday, June 5, 2012

Setting up and accessing a remote maven repository

Now that we've reviewed the basics for maven it's time to explore one of the more common situations in a maven project, setting up and accessing a remote repository. For any team greater than one person (which I'm guessing covers a slim portion of projects out there) and projects with more than a single executable (I'm guessing there is one or two of these types out there) you'll need a place to build the building blocks for more advanced projects (such as a utility package or a database entity project).

Creating a remote repository

While many people will say finding a place to store your repository would be the first thing you should consider I say that is the second thing you should do, the first thing is decide how you want users to access the repository and how you want contributors to upload content to the repository. Do you want to make it available over http? Will you need to use the SCP protocol to upload content? Are all your machines the same (Windows vs Linux vs Mac) and only internal access is necessary so a file:// protocol would work? These all will make a difference where you put the repository. After these questions are answered you can pick a server that fits these parameters.

Adding a deployment destination to a project

Now that you've decided where to place your project you'll need a way to add it to your project. Deployment locations are handled in the distributionManagement section of the pom file. It goes at the end of the file after the dependencies section and a sample distribution section appears below:
<distributionManagement>
  <repository>
    <id>serverId</id>
    <name>Example Upload Location</name>
    <url>scp://server/srv/maven/repository</url>
  </repository>
</distributionManagement>
Pretty simple right?  There are really two important parts of this snippet, first is the id of the server and second is the URL. The URL's significance should be obvious so I'll focus on the id field. The reason the id field is important is because that is the link between the pom file and this server setup and the personal field setup for this server in the settings.xml file. Depending on what type of URL you use, such as scp, you need additional information, like authentication and directory/file permissions, to perform the task so without further ado lets look at:

Settings.xml

Up until now we haven't had to worry about maven's other configuration file as nearly all tasks handled through the pom file don't need any additional configuration. Technically, if you were to use a file protocol for the deployment you still wouldn't need to configure a server in settings.xml but I have yet to see a system that could use that effectively. While you can configure many different things, such as a proxy or different profiles, through the settings.xml file the only major one that most people will need to use is the servers section. However, if you want to to learn more about the settings.xml file you can do so here. The entire file isn't all that big so reviewing it is quick. For a final note about the settings.xml file is where to find it; the file is located in each user's home directory (on linux it would usually be at /home/<userName>/.m2 and in windows usually C:\Users\<userName>\.m2, your mileage may vary).

servers

The important part of the settings file for distribution management is the server section. In this section you can define personal information about connecting to various servers. In the pom file you define the URL (some would ask why this wouldn't also be here but you can use the same server for multiple functions so the URL needs to be in the pom for different setups) but the rest of the information is here in settings (I'm guessing you may not want your user information broadcast to the rest of the world). A typical server setup looks like the following:
<servers>
  <server>
    <id>serverId</id>
    <username>my_login</username>
    <password>my_password</password>
    <privateKey>${user.home}/.ssh/id_dsa</privateKey>
    <passphrase>some_passphrase</passphrase>
    <filePermissions>664</filePermissions>
    <directoryPermissions>775</directoryPermissions>
  </server>
</servers>
First, if you go back up to our distributionManagement example you'll notice that the id fields match. That would tell maven to use the credential and permissions here when uploading content to the remote repository. You should either enter a password here or is private key/passphrase entry. You should not use both. The permissions are used for the directories and files created on the remote system. If you need an explanation on what the numbers mean you can search for unix file permissions or click here.

A quick bit on security

Starting with Maven 2.1 you can encrypt your password so even if someone managed to get a hold of your settings file (I'm assuming here that you don't give access to this to anyone other than yourself) they still couldn't see your password. Plus, administrators always get nervous when passwords are available in plane sight. If you want/need to encrypt your password I would just follow the instructions on the maven site to set it up here.

Adding a remote repository to a project

There are a plethora of reasons you may need to add a repository to your project.
  • Your company has a policy that prohibits downloading software packages directly from the web so you need to connect to a mirrored main repository inside the company
  • You need to connect to a third party vendor for additional software packages
  • You need to connect to an internal repository to use internal software APIs
Whatever the reason, there is a simple way to connect a maven project to one of these repositories. First, you need to add a repository to the repositories section of the pom (just before the dependencies section. The entry would look like the following:
<repositories>
  <repository>
    <id>java.net.maven1</id>
    <name>java.net</name>
    <url>http://download.java.net/maven/2</url>
   </repository>
</repositories>
Like the distribution management element above the name is just a name you want to see. For the id, it only matters if you need additional authentication information for the server you're connecting to. Since most access is over http and unauthenticated it usually doesn't matter. However, if you needed to lock down even the pull and ended up using something like scp then you'd want to make sure the id matches a server defined in settings.xml (see above).

2 comments:

  1. My cousin recommended this blog and she was totally right keep up the fantastic work!

    Maven company Set Up

    ReplyDelete
  2. Maven has the worst documentation.

    ReplyDelete