Using Maven Alfresco SDK with the Enterprise edition

April 10, 2013 - tagged #alfresco #maven #sdk #build

If you're an Alfresco aficionado, you should already know that last year we've released a new Alfresco SDK to make developer's life easier and to provide a solid, consistent and reliable way to manage your Alfresco (customisation) projects.

If it's the first time you hear about this, start with Gab's post to read about the project's history and all pointers.

In both cases, you may have missed the 1.0.1 release, whose biggest improvement is to allow the SDK to work with Alfresco Enterprise 4.1.2 (and later) versions. Earlier versions are not supported at the moment. This post guides you through all the steps to build an Alfresco Enterprise customisation using the Maven SDK.

Prerequisites

In order to get at the bottom of this tutorial you need credentials (username/password) to access the Alfresco Nexus instance), where the Enterprise artifacts are hosted; use the Nexus web interface to search for dependencies, check versions and other coordinates of the artifacts you need.

If you are an Alfresco customer and you want to request your credentials, you can follow this internal article

And Maven 3.0.x of course.

That's it. No database nor tomcat needed. True story.

Generate a Maven Project using the archetypes

First step is to generate a Maven project; for simplicity we will use the alfresco-amp-archetype, although the very same steps apply for the all-in-one archetype.

mvn archetype:generate -DarchetypeCatalog=https://artifacts.alfresco.com/nexus/content/groups/public/archetype-catalog.xml -Dfilter=org.alfresco.maven.archetype:

The following command will ask you to define the following parameters:

archetype - at the time of writing there are only 2 types of archetypes available: alfresco-allinone-archetype (1) and alfresco-amp-archetype (2). Let's go with 1
groupId - no special rules apply, you can choose any string you want. In my case I choose it.session.alfresco
artifactId - as above, with the difference that the artifactId will also be the name of the folder that Maven will create as a result of the current command execution. I choose session-repo-amp
version - the SDK version to use. It is very important that you choose option #2 (1.0.1) or above, otherwise the generated project will fail during the first build.

You will be asked to confirm all properties; type Y.

BUILD SUCCESSFUL? Let's move on!

Building the Maven Project using the community edition

Before testing the build with the Enterprise edition, it is strongly advised to try building with the community first.

The downside of this approach is that you will have to download all Alfresco Community dependencies first and - after that - all Alfresco Enterprise ones. If you have a slow connection, you may consider to skip this step and move to the next one; however, if you're having a hard time with the SDK (Maven sometimes can be a bitch) I advise you to test this approach.

It is as simple as

cd session-repo-amp && mvn integration-test -Pamp-to-war

(Maven will download roughly 300Mb during the first build; this is probably the best time to take a break)

Your command-line shell should end up with

INFO::Started SelectChannelConnector@0.0.0.0:8080
[INFO] Started Jetty Server

Point your browser to http://localhost:8080/session-repo-amp and try to login using admin/admin; if everything works as expected you can move to the next section.

Configure access to private repositories

Open your ~/.m2/settings.xml (or create one if it does not exist) and define the following item

<settings>
  ...
  <servers>
    ... 
    <server>
      <id>alfresco-private-repository</id>
      <username>your_usernmae</username>
      <password>your_plain_password</password>
    </server>

If you don't like to write plain passwords in XML configuration files (like me), I strongly advise you to follow the Maven tutorial on password encryption, but not before running the first successful build with the Enterprise edition. Just keep it for later.

NOTE! If you are new to Maven, I strongly advise to comment out any configurations from your settings.xml (at least for the first run), since mirroring delegates the entire artifact resolution to one central repository which may have been wrongly configured, leading to unresolved artifacts during the build.

Switch your project to Enterprise

Open session-repo-amp/pom.xml and set the following property values

<alfresco.version>4.1.2</alfresco.version>
<alfresco.groupId>org.alfresco.enterprise</alfresco.groupId>

You also need to change the repository configuration: instead of using the public Alfresco Maven repository (defined in your current pom file as alfresco-public), we need to switch to the private one. We don't need to add a new , since all public artifacts are also served through the private repo.

<repository>
  <id>alfresco-private-repository</id>
  <url>https://artifacts.alfresco.com/nexus/content/groups/private</url>
</repository>

Make sure that the repository matches with the one specified earlier in the settings.xml file

Run it (again)

As before:

cd session-repo-amp && mvn integration-test -Pamp-to-war

And now?

Why don't you leave a message on the discussion list and share your development experience with the rest of the community? Also, if you have problems with the build, that's the right place to ask for help.