Posts tagged OpenSource
From the grounds up, your Maven powered Alfresco dev box
Jan 14th
The target
To start your Alfresco development experience, you need a development environment. Let’s say you’re more into this Maven and you’d rather leverage its capabilities instead of using the default ant based build system provided along with the SDK. In this tutorial, I’ll guide you through the process of setting up from scratch your development environment. And by saying “from scratch”, I really mean it: we’ll start from a fresh installed Linux box and the we will add piece over piece until we’ll be see the Alfresco flower on our browser. This will be a *basic* tutorial, just to put in place the foundation for later improvements.
I’m actually performing these steps in a virtual machine, so that next time a quick&dirty Alfresco PoC is required I might use this very same VM to start right away from a known, dev ready point.
UPDATE: the Maven project structure I end up with at the end of this article can be downloaded directly from GitHub.
Operating System
Ok, I assume you know your stuff and don’t want to get a bore-some lesson on how to install Linux. The whole internet is polluted by billions of guides and tutorial since 199x, anyway, so let’s just say I just completed the install process of Mint7 and I’m at my very first login. I would go for Mint8 if my current connection was fast enough to download it before I finish writing these notes, but whatever, there’s nothing really bad in v7.
Tools
The shopping list here includes a JDK, Maven and… well, that should be it, theoretically. Unfortunately, due to a nasty regression, we’re going to need a db. My choice goes to MySQL.
MySQL
First thing first, let’s install it:
~$ sudo apt-get install mysql-server
When this is done, we have to create the db Alfresco is going to use:
~$ mysql -u root mysql> CREATE DATABASE alf_jetty; mysql> GRANT ALL ON alf_jetty.* TO 'alfresco'@'%' IDENTIFIED BY 'alfresco';
Username and password are the default for the maven stuff we’re going to use.
Java
Java™ 5 has already passed on, let it rest in peace. Instead, go and install Java™ 6:
~$ sudo apt-get install sun-java6-jdk
Maven
Hold on the temptation of installing Maven 3 or to ask apt-get to do this task for you. We’re going to the official download page and following the links to get the latest stable 2.x release. You should end up with something like apache-maven-2.2.1-bin.tar.bz2 on your file system. Then do the following:
~$ cs /opt ~$ sudo tar xvjf apache-maven-2.2.1-bin.tar.bz2 ~$ sudo ln -sfv /opt/apache-maven-2.2.1/bin/mvn /usr/bin/mvn
There are less intrusive ways to bring your downloaded application into your PATH, but this is the quickest possible. Let’s go on to the next step.
Plumbing
We’re almost there, we just have to lay down our projects. Let’s start with the Alfresco repo extension:
~$ mkdir -p development/alfresco-showcase ~$ cd development/alfresco-showcase alfresco-showcase$ wget http://download.skuro.tk/alfresco-showcase/pom.xml alfresco-showcase$ mvn archetype:generate -DarchetypeGroupId=com.sourcesense.alfresco \ -DarchetypeArtifactId=maven-alfresco-extension-archetype \ -DarchetypeVersion=1.9.1 \ -DgroupId=it.sk.alfresco \ -DartifactId=alfresco-showcase-extension \ -Dversion=1.0-SNAPSHOT \ -DarchetypeRepository=http://maven.alfresco.com/nexus/content/repositories/releases \ -DinteractiveMode=false
The POM I’m making available here is just a very basically one, I’m using it here just for you to speed up the process.
UPDATE: as others pointed me out, it looks like you somehow need to download such a pom for the whole thing to stand up. That’s simply not true, I’m just building a more complex dev environment and it’s better if we have some structure in place. This includes having a parent project, along with its parent pom, with nested projects registered as its modules. These will come in the next posts. But that’s just part of the reason for this pom to be here: I also tend to be lazy, so that letting you download it was easier than explaining myself. Note to self: thou shalt not post anything at 2am.
First achievement
Ok, let’s stop here now and see what we’ve done by now. Go to the alfresco-showcase folder and type:
alfresco-showcase$ MAVEN_OPTS="-Xmx512m -XX:MaxPermSize=128m" \ mvn clean install -Prun
This will start a local jetty instance where Alfresco 3.2 community will be deployed. So, if you now point your browser to http://localhost:8080/alfresco you will finally see that flower we talked about at the beginning of this post.
Next steps
That’s it for now, but other blocks are still missing: what about AMPs? And WCM? And does Share fits in the picture? I’ll cover all the points in the next episodes of this series. See you there!
Alfresco and LDAP sync lock my Admin no more!
Sep 15th
On the custom Alfresco Enterprise project I’m working we use LDAP sync to import users from a Novell eDirectory server[1]. Now, it happened from time to time that the user Alfresco binds itself with, i.e. the LDAP admin user, got locked in eDirectory as a “Intrusion prevention” mechanism or something like that.
The LDAP sysadmin said we were guilty of providing wrong credentials too many times when logging in. Which is weird, since most of the time the LDAP sync went well, which meant that either that sysadmin was seldom changing back and forth the Admin credentials or something Evilâ„¢ was going on under the hood. I personally feared for the latter, but let the issue wait a bit, since staging environments seemed to work just fine.
Then, when my dev team grew up with three more people, the issue worsened terribly, with the admin account locked almost any hour. I really started to get bothered by it, and did some investigations.
It turned out, it was all working “by design”, in the sense that yes, our Alfresco was providing wrong credentials and yes, the admin account was properly configured. This is how it went.
To be 100% sure our Alfresco configuration was correct, apart from checking every configuration file from here to eternity, I wanted to sniff the network connection to the LDAP server. When networked systems fail to work together, I always feel like I need raw network data.
Made a socat tunnel[2] to look at data BEFORE it entered the encrypted VPN connection, started Alfresco and waited. And, eventually, got it: I expected one bind connection request, I got more. Plus, the first three or four attempts were using almost random user accounts, while the last showed the known LDAP admin user name and the wrong password! WTF?
A closer look at the Alfresco LDAP connector solved the mistery. Here’s an excerpt from that code:
// Correct principal invalid password env = new Hashtable(initialDirContextEnvironment.size()); env.putAll(initialDirContextEnvironment); env.put(Context.SECURITY_CREDENTIALS, "sdasdasdasdasd123123123"); try { new InitialDirContext(env); throw new AuthenticationException( "The ldap server at " + env.get(Context.PROVIDER_URL) + " falls back to use anonymous bind for a known principal if invalid security credentials are presented. This is not supported."); }
That’s it: Alfresco performs intentionally a number of connections that are supposed to fail, in order to infer some LDAP server configurations. The code presented here above is what made eDirectory lock the admin user: when our 5~6 developer environments started up, almost simultaneously at the morning, they performed too many wrong login attempts with the correct user name in a row before the first one eventually started using both the valid username and the correct password.
Setting up the allowed failed logins on eDirectory for the local testing environment, finally, solved this hidden and tedious issue. Still unclear if the Alfresco approach is really a smart one, due to some limitations of the LDAP handshake protocol I’m not aware of (well, I’m not that LDAP expert, after all) or such intentionally failing logins can/should be deleted/changed. What do you think?
[1] Here Alfresco happens to be MultiTenant, but still we are able to import users&groups from the Directory. Which has been my very first successful customization task as an Alfresco dev 
[2] I’ll eventually end up using socat for brushing my teeth, I guess
Deploy your site on Nexus™ OpenSource
Jul 6th
These days I have to provide a documentation site to one customer, so I started playing around with the maven site plugin and I created a really beautiful set of pages that will be able to teach all the details of my project to a chimp. Now, it’s time to make it available for that chimp: since my artifacts are delivered through Maven on a Nexus handled repository, I opted for the same Nexus instance to host my site. Let’s see what’s needed to achieve this result.
First of all, you have to download Nexus™. The OpenSource version is fine, so that you can start to play around before you eventually decide it’s time to go Pro. You can get Nexus from here. In the following I’ll assume you downloaded the quick start bundle, so that you’ll have a separated application server for Nexus shipped within the same zip file you downloaded. If you opted for the WAR download, you probably already know how to go
Configure & run Nexus
The default configuration provided with Nexus is probably fine for having just a quick try, but I suggest to configure one or two things, just to start feeling comfortable with the nice toy you’ve just downloaded. So, unzip the Nexus archive whereve you prefere, you will end up with a folder named like nexus-webapp-blabla. We will call it $NEXUS_HOME.
Open the file $NEXUS_HOME/conf/plexus.properties. Here I changed only two lines, namely the TCP port where the application will bind to and the storage area where all the artifacts (and sites!) will be stored. Here is my configuration file:
application-port=8082 application-host=0.0.0.0 runtime=${basedir}/runtime apps=${runtime}/apps nexus-work=/var/sonatype-work/nexus-opensource webapp=${runtime}/apps/nexus/webapp webapp-context-path=/nexus security-xml-file=${nexus-work}/conf/security.xml application-conf=${nexus-work}/conf # If this file is present, it will be used to configure Jetty. jetty.xml=${basedir}/conf/jetty.xml # Uncomment this to use the debug js files #index.template.file=templates/index-debug.vm
Since I changed the storage area, I had to create the folder configured in nexus-work:
~ skuro$ cd /var var skuro$ sudo mkdir -p sonatype-work/nexus-opensource var skuro$ sudo chgrp -R admin sonatype-nexus var skuro$ sudo chmod -R g+rwx sonatype-nexus
NOTE: the permission you set on the created folders must match the user under which you’ll run Nexus.
Now it’s time to let it run. Nexus comes shipped with wrapper scripts that are able to launch the application on several different platforms. I’m running MacOSX on an Intel machine, but you’ll have to check inside the $NEXUS_HOME/bin/jsw folder to find the wrapper that best suits your system configuration.
~ skuro$ cd $NEXUS_HOME nexus-webapp-1.3.4 skuro$ ./bin/jsw/macosx-universal-32/nexus start
Done. Now if you point your browser to http://localhost:8082/nexus you should see it’s dashboard:
The default admin username/password is admin/admin123, you can log in now and play around Nexus.
Configuring a repo for your sites
You don’t want to mess up artifacts and sites, it will be a lot neater if you have a separated repo for each kind of deliverable. When logged in as admin in Nexus, click the Repositories link on the left menu and then select Add->Hosted repository. A form will appear where you will have to enter the details of the repo you’re creating. Edit it to look like this:
Click on Save and the new repo will appear on the Repositories list, with the base URL you will have to use in your POM configuration. But let’s stick on Nexus configuration for now, we still have something to do here. Let’s create a Repository Target, which will be used to fine tune our configuration for our test project. Click on the Repository Targets in the Administration menu on the left and then Add. Another form will appear which you’ll fill like this:
OK, we’re almost there, we just have to set some authorization stuff and we’ll be done with Nexus. In Nexus, the security model is made of Privileges, which describe actions like “read” and “write”, Roles, that define a set of Privileges, and Users, to whom you can grant both Roles and Privileges. So, first of all click on the Permissions link from the left menu, and then Add->Repository Target Privilege. You’ll end up with something like this:
The Role and User creation is really straightforward, I’ll leave it to you to figure out how to create a Role that aggregates the Site repo privileges and a User that will be granted that role. In my test configuration, the User and the Role are both called site-dev.
Configuring the Maven site plugin
Now that we created a repo to host our sites, let’s try to deploy something in it! We have to do basically two things
- create a project, if we don’t have one already
- configure the repository where the site will be deployed in the distributionManagement section of the POM
- configure the user credential that will be used to upload the site
Developers are supposed to be lazy, otherwise automating things won’t be that effective. Knowing that, you can use this test-site-project to test your configuration. It is already a project with a parent POM and a module, just to prove that multi module projects are not an issue here 
Before uploading the site, make sure that the site URL in the parent pom.xml matches your Nexus URL, and add a configuration in your $MAVEN_HOME/settings.xml to identify your user against Basic HTTP when deploying the site:
<server> <id>nexus-local-opensource</id> <username>site-dev</username> <password>password</password> </server>
Remember that the site <id> must match the distributionManagement repository <id>.
Deploy it!
Ok, we got it, now we have a (hopefully) working configuration we can use to upload and make available your site through Nexus. To prove yourself that ir really works, just run this commands:
test-site skuro$ mvn site:site test-site skuro$ mvn site:deploy
Done! Now, if you used the configuration I showed you, you should be able to access the site at the URL http://localhost:8082/nexus/content/repositories/site-repo/test-site/index.html
Conclusions
Using Nexus as a single provider for both your artifacts and the associated sites can be easier to maintain, and I hope this post will help you to start using this configuration. The next step will be the configuration for the maven release plugin, that can be easily achieved using maven CALM. But this is stuff for another post, so if you want to know more about it just search the Net [1] [2] or stay tuned!
