Github: Deploy your own Maven repos!

I’ve been using other people’s maven repos for years.  Emailing jars around, pushing them into drop boxes, checking out source code just to build binaries, etc. etc. etc…. And this was all AFTER maven existed.

Why ?

Because I never realized HOW EASY IT IS to create YOUR OWN maven repository.  

When maven automagically gets your dependenices, I always envisioned that there was some massive, big-brother java servlet running along in the background which was able to dynamically reroute requests, based on namespaces, to different places on the web.

Well guess what THATS NOT HOW IT WORKS.  Maven is simple when it comes to deployment.  

I used this blog by chad emerick: http://cemerick.com/2010/08/24/hosting-maven-repos-on-github/, which is alost 2 years old, to create my own maven repo today, in under 30 minutes.  It really is painless.

IT STILL WORKS.

I was kind of surprised to find that this was so simple :

1) Maven repos are not that hard to host – they are just a directory structure.
2) Github has not done anything to block or prevent this sort of thing.  Thanks 🙂
3) The only meta data you need to package a jar and allow remote accession of it is encoded in about 8 lines of a simple “server-side” pom file. 

As an example, I’m just going to use a simple java project which I wrote to print a file tree out at the terminal, really useful for adding code snippets that looking into big ugly hadoop directories during unit tests.  Or just for printing out directory structures for other java text based tools.  Its not super complex, and makes for a good tutorial.

1) Make sure you have a proper java/maven project.  To witness the magic of maven, you really want to deploy a jar file.  Your pom should look something like this :

<?xml version=”1.0″ encoding=”UTF-8″?>
<project xmlns=”http://maven.apache.org/POM/4.0.0″ xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”
    xsi:schemaLocation=”http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd”>
    <modelVersion>4.0.0</modelVersion>

    <groupId>org.rudolf.utils</groupId> <!– your namespace goes here.  anything will do –>
    <artifactId>TPrintUtils</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <packaging>jar</packaging>

    <name>TPrintUtils</name>
    <url>http://jayunit100.blogspot.com</url> <!– this doesn’t matter ! its just meta data –>

    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>2.3.2</version>
                <configuration>
                    <source>1.6</source>
                    <target>1.6</target>
                </configuration>
            </plugin>
<!– This is important : You want to make a jar file ! Otherwise you are wasting your time.  And this plugin is pretty much automatic, so don’t be afraid… add it to your build. –>
            <plugin>
              <artifactId>maven-assembly-plugin</artifactId>
                <configuration>
                 <descriptorRefs>
                  <descriptorRef>jar-with-dependencies</descriptorRef>
                 </descriptorRefs>
                 <archive>
                   <manifest>
                     <mainClass>fully.qualified.MainClass</mainClass>
                   </manifest>
                 </archive>
                </configuration>
             </plugin>
        </plugins>
    </build>
    <dependencies>
           ……….       
    </dependencies>
</project>

2) Run your build : “mvn install”, from the root directory of your project.  We want to make sure everything succeeds before deployment.

3) You will now  :
   1) Create a new github.com project for your maven repository, and clone into it. Note – this is not where you developed your source code.  This is separate.  This can be confusing – because you will have a pom.xml file in it — but it won’t be the same old pom.xml file that your used to dumping apache-commons and apache-io etc… into.  Rather, its a pom.xml that describes how your repository is structured.  You dont need to understand all of this – but – when the car stalls, it doesn’t hurt to know a little bit about the way the engine works.

   2) Okay – so here is what will happen next.  You will create  a pom.xml in the root of your maven repository, and it will should something like this :

<distributionManagement>
    <repository>
        <id>repo</id>
        <url>https://github.com/jayunit100/maven-sandbox-repo/raw/master/releases</url>
    </repository>
    <snapshotRepository>
        <id>snapshot-repo</id>
        <url>https://github.com/jayunit100/maven-sandbox-repo/raw/master/snapshots</url>
    </snapshotRepository>
</distributionManagement>

    NOTE.  These directories don’t even EXIST on github (before, or after deployment), so don’t go looking for them.  Rather, they will tell  maven where your repository artifacts are.
  
   3) Now, again from your root project directory, deploy a maven repository using this command :

    Obviously, you need to replace the yellow highlighting with the exact path to the directory where you cloned your git project.

   4) Okay — so finally, by adding all the files (git add *) and commiting them, you are essentially “deploying” a remote maven repository, with all necessary meta data / jars / etc .  No need learn any new magical maven syntax or anything – just git add, git commit, and git push.

   5) You’re now 100% ready to go off and FOLLOW THIS TUTORIAL : http://cemerick.com/2010/08/24/hosting-maven-repos-on-github/.

Finally, when you’re all done, you will be able to simply paste your repository / dependency info into maven just like you’ve always done for so many projects, into your own maven dependencies in your pom.xml/ivy.xml/blah.project for your ant/maven/lein/grapes/whatever projects, except …

THE PROOF 

Finally, you may want to PROVE to yourself that your new maven repo can really be downloaded and used by anybody, by simply copying and pasting some xml into their pom file.  You need to know that this really is working (after all, you did a mvn deploy of your project, and its probably already sitting in your local .m2 folder — so how can you be sure that the remote repo is working ) ? 

Go ahead and go into your .m2 home folder, and remove your repo (in my case, this meant running this command from inside of .m2/ 

rm -rf org/rudolf 

Now, build a simple java/maven project, and add your repository/dependencies xml blocks into the pom.xml, and run 

maven install

From the terminal.  And you will see this :

Downloading: https://oss.sonatype.org/content/repositories/snapshots/org/rudolf/utils/TPrintUtils/0.0.1-SNAPSHOT/maven-metadata.xml
Downloaded: https://github.com/jayunit100/maven-sandbox-repo/raw/master/snapshots/org/rudolf/utils/TPrintUtils/0.0.1-SNAPSHOT/maven-metadata.xml (777 B at 0.3 KB/sec)
Downloading: https://github.com/jayunit100/maven-sandbox-repo/raw/master/snapshots/org/rudolf/utils/TPrintUtils/0.0.1-SNAPSHOT/TPrintUtils-0.0.1-20120405.230643-1.pom
Downloaded: https://github.com/jayunit100/maven-sandbox-repo/raw/master/snapshots/org/rudolf/utils/TPrintUtils/0.0.1-SNAPSHOT/TPrintUtils-0.0.1-20120405.230643-1.pom (3 KB at 2.6 KB/sec)
Downloading: https://github.com/jayunit100/maven-sandbox-repo/raw/master/snapshots/org/rudolf/utils/TPrintUtils/0.0.1-SNAPSHOT/TPrintUtils-0.0.1-20120405.230643-1.jar
Downloaded: https://github.com/jayunit100/maven-sandbox-repo/raw/master/snapshots/org/rudolf/utils/TPrintUtils/0.0.1-SNAPSHOT/TPrintUtils-0.0.1-20120405.230643-1.jar (5 KB at 4.1 KB/sec)