This post explains how to use the Jenkins SCP plugin to copy the freshly built application to another machine using SCP. This is useful when you need to copy an application to a specific machine or another environment without exposing it publicly.

Although this post is focused on Jenkins, other continuous integration servers have equivalent capabilities.

Why copying instead of deploying to a repository?

In addition to the fact that you may not use Nexus or Maven, there are a couple more advantages to copying an application instead of publishing it.

First, using copies, your application is kept private. Your artifact must cross the whole test pipeline before being published to a repository. So, you know that your team won’t rely on an untested (or at least, not completely tested) artifact.

Secondly, all the versions built by Jenkins will be copied. The previous approach used only the latest, which runs the risk of skipping some versions, making it hard to know when a regression was introduced.

Let’s move on and modify the pipeline. Our previous pipeline was the following:

The journey of the source code from the developer machine to the test environment

We update it slightly, to the following:

A slightly updated pipeline using SCP instead of Nexus

To implement this pipeline, install the Jenkins SCP Publisher Plugin (actually named Hudson SCP Publisher Plugin):

Then, you need to configure the host on which you want to upload the application. In the global configuration of Jenkins, scroll down to the SCP repository hosts section, and configure your new SCP Site:

Note: The SSH and SCP plugins must be configured separately.

Then, in the Jenkins job building the application, we add a post-build action to upload the artifact to the host. Check the ‘Publish artifacts to SCP Repository’ check box, and select the site you added. You also have to select the files you want to upload. In the following picture, we select the war file we’re building:

Configuration of the uploaded files

The ‘destination’ allows you to define the final location of the file you deploy. This location is relative to the root set in the site configuration. In our case, it’s already the Tomcat deploy folder. You can upload several sets of files, but to only one site. If you have to deploy to several sites/hosts, you will need one job per site/host (making sure that each job deploys the same files).

Once done, we’re good to go. Execute your build, and the files will be uploaded. The rest of the pipeline can be more or less the same as in the previous post, except that now you already have the application in place. If you’re targeting an already running environment supporting hot-deploy, then you don’t even have to do anything else after this deployment.

Conclusion

This blog post shows how the Jenkins SCP plugin can be used to support continuous delivery, and actually provision your application to your host. It’s another way to achieve continuous delivery simply. This approach is particularly well suited when your host already contains your application server, and when this application server supports hot-redeployment.

So to make everybody happy, you start releasing the application weekly. However, releasing is generally a hard-core process, even for the most automated processes, and requires human actions. As the release date approaches, stress increases. The tension reaches its climax one hour before the deadline when the release process fails, or worse, when the deployment fails. We’ve all been in situations like that, right?

This all-too-common nightmare can be largely avoided. This blog post presents a way to deal with the above situation using Jenkins, Nexus and SSH. The application is deployed continuously and without human intervention on a test environment, which can be checked and tested by the customer. Jenkins, a continuous integration server, is used as the orchestrator of the whole continuous delivery process.

The principles of Continuous Delivery

Continuous Delivery is basically a set of principles to automate the process of software delivery. The overall goal is to continuously deliver new versions of a software system.

It relies on automated testing, continuous integration and automated deployments. The application is packaged and deployed to test and production environments, resulting in the ability to rapidly, reliably and repeatedly push out enhancements and bug fixes to customers at low risk and with minimal manual overhead.

Continuous Delivery is based on the pipeline concept. A delivery pipeline is the process taken by the code from the developer’s machine to production environments, particularly pipelines defined for the testing stages and the deployment process.

A Simple Pipeline

Continuous delivery can be quite hard to set up for complex systems. We recommend starting with a simple configuration. Let’s take a simple web application deployed on an application server such as Tomcat or JBoss.

The journey of the source code from the developer machine to the test environment

The code of our application is hosted on a source code management (SCM) server. It can be Git, Subversion or anything else. It’s the entry point of our pipeline.

Our continuous integration server (Jenkins) pulls the code from the SCM. It builds and tests the application. If all tests are green, the application is packaged and deployed to an artifact repository (Nexus in our context). Then, Jenkins triggers the deployment process.

To achieve this, Jenkins connects to our host machine using SSH, and launches the deployment script. In this example, the deployment script is a simple shell script redeploying and restarting the application.

Finally, when the deployment is done, we check the availability of our web application.

Implementing the pipeline

The presented pipeline is quite simple, but works pretty well for most web / JavaEE applications. To implement it, we need a Jenkins with two specific plugins (the SSH plugin and the Groovy Plugin) and a host machine available through SSH.

Preparing Jenkins

The first thing you need is to install the plugins in Jenkins: – The Jenkins SSH plugin allows you to connect to the host machine by SSH and execute commands; the Hudson Groovy Builder to execute Groovy code. We use Groovy to check the deployment result. However, you can use other options (unit tests, nagios…)

Once those two plugins are installed, you need to configure the connection to the host machine. In the Global Configuration page of Jenkins, scroll down to the SSH Remote Host section and add a host. Enter the machine name or the IP address, and the credentials. You can also use a key file.

Add an SSH connection to Jenkins

Once done and saved, it’s time to create our Jenkins Jobs supporting our continuous delivery process. To keep this example simple, we divide our process in two jobs:

• The first job compiles, tests, builds and deploys the application. If successful, the new application archive is deployed on our Nexus repository.
• The second job is triggered upon the success of the first job. It connects to the host machine, and executes a shell script. Once done, it executes a simple Groovy script to check the deployment success. We use Groovy for its simplicity in making HTTP connections and retrieving the result. However, you can use plenty of other ways.

The first job configuration is not specific to the continuous delivery pipeline. It’s generally a regular job deploying the artifacts to a Maven repository. So, a simple Maven Job executing mvn clean deploy upon a source code update is enough. If you want to divide this job into several steps, have a look at this post. In our example, we deploy the application to a Nexus repository.

The second job is more interesting. Create a new freestyle project job. This job is triggered upon successful execution of the first job. So select None as Source Code Management and indicate the previous job name in the Build after other projects are built option.

The build is started when the previous build succeeds

In the Build section, add a first build step, and select Execute shell script on remote host using ssh. Select your host, and add the script. You can also use a command directly, and execute a script already present on the host.

Launch the deployment script

Preparing the application host

At this point, we have a Jenkins job connecting to the host and executing some commands. To simplify, we focus only on the application deployment and not on the environment setup. So we consider that the host is ready to be used. The deployment script follows this basic pattern:

1) Stop the application
2) Retrieve the new application
3) Deploy the new application
4) Restart the application


First, if the application runs, it should be stopped (except if your application server supports hot-redeployment). Then, we retrieve the application package. This step consists of downloading the latest version of our application from a repository. Once downloaded, the application is deployed, so either copied to a deploy folder, or unpackaged to a specific location. Finally, we restart the application.

Step 1) and 4) are dependent on your application server, but if you’re using Linux upstart scripts, it should be something like:

stop my_application
...
start my_application

Or if you’re using a service:

/etc/init.d/my_application stop
...
/etc/init.d/my_application start

To retrieve the latest version of our application, we’re relying on the Nexus REST API and a script to download the latest version. This script is available here, and so should be available and made executable on your host (Note: this script requires Curl). With this script, getting the latest version of our application is quite simple:

...
download-artifact-from-nexus.sh \
 -a mycompany:myapplication:LATEST \
 -e war \
 -o /tmp/my_application.war \
 -r public-snapshots \
 -n http://mynexus \
 -u username -p password
...

We first specify the Maven artifact to download, and so use the GroupId:ArtifactId:Version coordinates. We use LATEST as version to download the latest version (a snapshot in our case). The -e parameter indicates the packaging type. Then, we indicate the output directory. The -r option specifies the Maven repository on which the artifact is hosted (check your Nexus configuration to find this value). The other options set the Nexus url and the credentials.

Deploying the application (step 3) depends on your execution environment. It generally consists of copying the downloaded archive to a specific directory.

So, to sum up, the following script can be a valid deployment script for a web application packaged as a war file executed on a Tomcat server:

export WEBAPP=Tomcat webapp folder
stop my_application
download-artifact-from-nexus.sh \
 -a mycompany:myapplication:LATEST \
 -e war \
 -o /tmp/my_application.war \
 -r public-snapshots \
 -n http://mynexus \
 -u username -p password
cp /tmp/my_application.war $WEBAPP
start my_application

So, if everything is configured correctly, once you commit a change to your application, this change should be deployed immediately to your test environment.

First, your application is tested, built and deployed on a Nexus repository. Then, a second Jenkins job connects to the host machine and runs a deployment script. This script retrieves and deploys the latest version of the application.

Checking the deployment

An improvement you could make is to check whether the deployment was performed correctly. For that, you can use Groovy. In the second Jenkins job, add a new build step: Execute Groovy Script. In the text area, just do a simple check like:

Thread.sleep(Startup_time)
def address = "Your_URL"
def url = address.toURL()
println "URL : ${url}"
def connection = url.openConnection()
println "Response Code/Message: ${connection.responseCode} / ${connection.responseMessage}"
assert connection.responseCode == 200

This simple Groovy script waits a couple of seconds (until your application is actually started), and connects to your application. If the application response is correct, then everything is fine. If not, the build is marked as failed, and you should have a look. Obviously, this simple script can be improved and adapted to your situation.

That’s it!

This blog post has presented a way to implement continuous delivery for applications using Jenkins, Nexus and a machine accessible using SSH. Obviously other combinations are possible.

Continuous delivery may be hard to achieve in one step, but as illustrated in this post, it can be set up pretty easily to continuously deploy an application to a testing environment.

Thanks to these principles, you make the development more reactive; we can immediately see the changes. Moreover, errors and bugs are detected earlier.

It’s up to you to tune your pipeline to fit your needs. For instance, pushing the application on the test environment nightly, instead of after every change.

akquinet tech@spree is now using continuous delivery principles in several projects. The results are really beneficial. The test campaigns were improved, and thanks to the pipeline, developers can focus on the devleopment of new features and bug fixes, while still seeing their changes immediately.

The technology radar captures the output from discussions, experiments, projects, and feedback from customers and developers. It synthesizes the results to inform global technology strategy decisions. It focuses on new technologies and methodologies with a high level of attraction. This document does not aim to provide an in-depth presentation of each technology, focusing instead on conciseness and highlighting the trends and state of the practice.

More information on http://radar.spree.de

We are successfully using PicketLink in several internal and external applications and it is also a foundation for many other frameworks like seam-security[3] or the GateIn[4] portal server.

The Problem

One of our customer applications is based on a customized version of GateIn 3.1.0 and uses PicketLink internally to load users from an LDAP. That application is facing an international rollout which requires it to talk to an additional LDAP store. However, this is a feature which is not yet fully supported in the version of PicketLink (1.1.5CR01) used in GateIn 3.1.0. The application is depending on a few quirks of GateIn 3.1.0 and our customizations to that. Therefore an update to a newer version of PicketLink or even GateIn is out of the question. The risk of braking changes or worse, subtle incompatibilities is too high.

To solve that problem, we explored the option to enhance PicketLink 1.1.5 CR01 to support multiple LDAP stores and use that patched version in GateIn. We successfully managed to create a fork of 1.1.5 that sequentially queries multiple LDAP servers. We made the modification available at GitHub. This blogpost describes the changes we made to PicketLink and their motivations.

PicketLink

The fact that PicketLink does not support multiple LDAP stores was not clear from the beginning. The configuration file (usually picketlin-idm-config.xml) happily accepts an arbitrary number of LDAP stores. The following listing shows a snippet from a valid configuration file with multiple stores defined:

picketlink-idm-config.xml:

<repositories>
  <repository>
    <id>PortalRepository</id>
    <class>org.picketlink.idm.impl.repository.FallbackIdentityStoreRepository</class>
    <external-config/>
    <default-identity-store-id>HibernateStore
    </default-identity-store-id>
    ...
    <identity-store-mappings>
      <identity-store-mapping>
        <identity-store-id>LDAP1</identity-store-id>
      </identity-store-mapping>
      <identity-store-mapping>
        <identity-store-id>LDAP2</identity-store-id>
      </identity-store-mapping>
    </identity-store-mappings>
    ...
  </repository>
</repositories>

Yet, there is a caveat. Only the last configured identity-store is used by PicketLink. So our first task was to understand where and why the other configured stores get lost.

PicketLink has an ObjectTypeIdentifier that tells it, what kind of object it is dealing with. This ObjectTypeIdentifier is not much more than a simple String. For users, it is usually configured to be ‘USER’ but this can be changed in the configuration file. During the bootstrap of PicketLink, it creates a HashMap from these ObjetTypeIdentifiers to map to the store that is configured for that specific type. And of course, if two stores define the same ‘identity-object-type’, they fall into the same bucket of the map. Every subsequent store overwriting the previous one.

The naive approach of just defining two different identity-object-types, one per store does not work. When PicketLink queries a user, it looks for the type of users and only looks in the identity store, that matches the ‘UserType’. The second store with a different ‘identity-object-type’ is never queried.

But this is exactly the entry point we decided to expand upon. The class PersistenceManagerImpl has a number of methods that eventually query an identity store. Three of those methods are actually used by our application. The query for a single user, the query for a list of users and the query for the count of users (instead of returning the list, the last call only returns the resultset size).

We modified each of those methods. Instead of just querying the store that matches the configured ‘ObjectType’ for user, the methods now query all configured identity-stores sequentially, merging the results. The map containing the identity-stores is easily available at runtime. The modfications are simple and straight forward.

One optimization, we made was to shortcut subsequent queries for users if we already have found a user. This implies the assumption, that a user is unique throughout all LDAP stores – in our usecase, this assumption is sound.

The following listing shows as an example the changes we made to the ‘findUser’ method. The ‘identityStoreMappings’ contain the configured ObjectTypeIdentifier as keys. We iterate over those keys and create new SimpleIdentityObjectTypes from each key. PicketLink will then choose the store to query based on the ObjectType and therefore query a different store each time. Finally, we collect and accumulate the results.

Modified PersistenceManagerImpl to find users in multiple LDAP store:

public Collection<User> findUser(IdentitySearchCriteria criteria)
  {
  // search cache
  ...
  // search all stores
  final Map<String, IdentityStore> identityStoreMappings = 
  getRepository().getIdentityStoreMappings();
  List<IdentityObject> identityObjects = 
  new LinkedList<IdentityObject>();
    for (String storeId : identityStoreMappings.keySet())
    {
    final Collection<IdentityObject> ios =
    getRepository().findIdentityObject(getInvocationContext(), new
    SimpleIdentityObjectType(storeId), 
    convertSearchControls(criteria));
      identityObjects.addAll(ios);
    }
    final List<User> identities = new LinkedList<User>();
    for (IdentityObject identityObject : identityObjects)
    {
      identities.add(createUser(identityObject));
    }
  // add to cache
  ...
  return identities;
}

This works fine for querying users. A first victory! But not yet the final result. Although PicketLink can now query for users, it is still unable to fetch the attributes, like names or mail-adresses from those users. The querying for attributes happens in another class: FallbackIdentityStoreRepository. The method ‘getAttributes(IdentityStoreInvocationContext invocationContext, IdentityObject identity)’ is responsible for that. We extended it in a similar fashion. First, we let PicketLink decide, which store to search for attributes first. If the resultset is not empty, we obvioulsy have found the user and can proceed as normal. This query can also be executed against a ‘Hibernate Store’ or any other store. If we were unable to find attributes that way, we iterate over all configured ‘identity-store-mappings’ again. This time also making sure, that we do not query the store that was used in the previous query again. If the user is present in any of the stores, we query that store for the attributes, hopefully finding them and proceeding as normal.

Modified FallbackIdentityStoreRepository to get attributes from multiple LDAP store:

public Map<String, IdentityObjectAttribute> getAttributes(...)
  {
  Map<String, IdentityObjectAttribute> results = new 
  HashMap<String, IdentityObjectAttribute>();
  IdentityStore toStore = resolveIdentityStore(identity);
  IdentityStoreInvocationContext targetCtx = 
  resolveInvocationContext(toStore, invocationContext);

  // expect user in first LDAP store
  if (hasIdentityObject(targetCtx, toStore, identity))
  {
    results = toStore.getAttributes(targetCtx, identity);
  }
  else
  {
    // check that the identity we are looking is configured in the
    // attributeStoreMappings
    if (toStore != defaultAttributeStore && 
    attributeStoreMappings.keySet().contains(identity.
    getIdentityType().getName()))
    {
      // check attributes for all LDAP stores
      for (String storeName : attributeStoreMappings.keySet())
      {
        IdentityStore userIdentityStore = resolveIdentityStore(new
        SimpleIdentityObjectType(storeName));
        // check that it is not the LDAP, we already checked a few 
        // lines ago
        if (userIdentityStore != toStore)
        {
          IdentityStoreInvocationContext otherLdapCtx = 
          resolveInvocationContext(userIdentityStore, 
          invocationContext);
          SimpleIdentityObject userFrIdentity = new
          SimpleIdentityObject(identity.getName(), 
          identity.getId(),
          new SimpleIdentityObjectType(storeName));
          if (hasIdentityObject(otherLdapCtx, userIdentityStore,
          userFrIdentity))
          {
            results = userIdentityStore.getAttributes
            (otherLdapCtx, userFrIdentity);
          }
        }
      }
    }
  }
  if (toStore != defaultAttributeStore)
  {
  ...
  }
  return results;
  }
}

With those changes in place, we are now able to query our users from an arbitrary number of identity stores and successfully fetch the attributes to those users. Our testcases are green and the application is behaving as expected with those modifications in place.

Bootstrap

There is only one minor annoyance left. During the bootstrap of GateIn, we import a number of users into a primary hibernate identity-store. The bootstrap first checks whether those users already exist and insert them if thy can’t be found. During that bootstrap, PicketLink appears to be in an imcompletely configured state. At that time, getIdentityStoreMappings() returns an empty map. Since we iterate over the keys of that map, our modifications aren’t querying anything and users, that already exist won’t be found. This results in an exception when the bootstrap tries to create them.

Those exceptions do not interfere with the application but they litter the server log. To avoid this strange edge-case of an incompletely configured PicketLink, we perform a check to see if the configured store-mappings are empty. When they are empty, we add the user-object-type to the keyset before iterating over it. Therefore we always query at least the store that is configured as the default store for users.

findUser result caching

One minor remark: During our debugging, we discovered a caching problem in PicketLink. GateIn first queries PicketLink for all users matching a certain criteria. And later in the rendering of the GUI, it performs individual queries for each user again. Therefore it makes a lot of sense to cache those users. However, The caching strategy of PicketLink caches complete searches, only. A second query for a list of users with the same criterias should result in a cache hit. However, individual queries for those users are always cache-misses. We decided to change that behaviour. The findUsers Method puts not only the ‘Result-Collection’ in the cache. It now also caches each individual user. Therefore all subsequent requests to findUser for each individual user can be answered directly from the cache. This dramatically reduces the number of LDAP queries performed by PicketLink. And since each findUser query now has to potentially go to every configured LDAP store, this can be quite significant.

Tuning performance – maximum LDAP results

According to the LDAP spec, each LDAP request returns maximum pages size of 1000 entries. After extending PicketLink to support multiple LDAPs, we were forced to potentially handle 1000 * n entries (where n is the number of configured LDAP Stores). As PicketLink doesn’t provide the capability to limit the result set out of the box, we also added this behaviour. (BTW, this is implemented in PicketLink since version 1.3.0.Final)

The PicketLink configuration file accepts an arbitrary number of name-value options. We decided to use the same option that is also used in later versions of PicketLink. The following listing shows the required configuration to set the result set size for an LDAP Store to 10 (You might want to set that number higher in real scenarios)

configure for each LDAP strore, picketlink-idm-config.xml:

<option>
  <name>maxSearchResults</name>
  <value>10</value>
</option>

The next step is to make PicketLink aware of the new option. We tried to keep our changes as local and as minimal as possible to keep the risk of unforeseen side-efects as small as possible. Instead of adding a new pair of getter/setter to the the ‘LDAPIdentityStoreConfiguration’, we directly access the options. The options from the configuration file are parsed into a hash map that is kept around and accessible at runtime through the LDAPIdentityStoreConfiguration and its MetaData. We decided to create a default value and lazily initialize a new instance variable in LDAPIdentityObjectImpl to control the result set size. Based on that number, we create a ‘javax.naming.ldap.PagedResultsControl’ object and add it to the existing LDAP request controls effectively limiting the result size. The following listing shows those changes:

public List<SearchResult> searchIdentityObjects(...)
  {
  // Set max results for query. Try to get from configuration 
  // file, first. Use {@link MAX_SEARCH_RESULTS_DEFAULT}, 
  // alternatively.
  try
  {
    List<Control> controlList = new ArrayList<Control>();
    if (requestControls != null)
    {
      controlList.addAll(Arrays.asList(requestControls));
    }
    // lazily load maxResults from configuration
    if (maxResults <= 0)
    {
      maxResults = MAX_SEARCH_RESULTS_DEFAULT; // default value
      try
      {
        maxResults = Integer.valueOf(getConfiguration(ctx).
        getConfigurationMetaData().getOptions().get(MAX_SEARCH_RESULTS).get(0));
      }
      catch (Exception e)
      {
      ...
      }
    }
    controlList.add(new PagedResultsControl(maxResults, 
    Control.CRITICAL));
    requestControls = new Control[controlList.size()];
    requestControls = controlList.toArray(requestControls);
  }
  ...
  }

Deployment

With all those issues sorted out, we had a working PicketLink implementation with only a few minor changes to the base version we started from. All our requirements are fulfilled and the required patches are clear and minimal.

To maintain our changes and to contribute our modifications back to the community, we decided to use GitHub. We started with a new GitHub project and checked in the unmodified PicketLink sources in version 1.1.5.CR01. We then formulated our own requirements in the form of issues against that github repository. We tracked and documented our progress by commiting our progress to github and updating the relevant issues.

We decided against a true fork of PicketLink in the form of a new, separate maven artefact. Since we do not build GateIn and PicketLink is integrated within GateIn, the benefit of such a fork would be minimal. Instead, we manually build our version of PicketLink and replace the jars inside GateIn. We already had scripts in place to create and configure GateIn for our different environments. Those scripts now also replace PicketLink in GateIn.

Conclusion

In this post we described required steps to extend PicketLink to support multiple LDAP stores at the same time. We described how and why we changed PicketLink.

An overview of our changes:

• Support multiple usertype mappings that each map to different LDAP identity stores.
• Iterate over the userTypeMappings, that have identity-stores instead of using the single one user-type mapping
• Define amount of LDAP search results for each LPAD store as option “maxSearchResults” via xml config file.
• Fixed performance issues caused by new implementation.

As sources are LGPL licensed, we do provide code on GitHub for public usage: https://github.com/akquinet/picketlink-idm

We also informed the PicketLink forum about our changes and they are looking into merging some of them back upstream.

You are welcome to try our modifications. To get started:

• download tagged sources
• build project locally
• replace picketlink-idm-core-1.1.5.CR01.jar and picketlink-idm-ldap-1.1.5.CR01.jar in GateIn

We would appreciate any feedback either via mail or direct through GitHub.

references:
[1] http://www.jboss.org/picketlink
[2] http://www.jcp.org/en/jsr/detail?id=351
[3] http://seamframework.org/Seam3/SecurityModule
[4] http://www.jboss.org/gatein

Happy New Year!
Moritz Grauel, Michael Schuetz

This blog post explains how you can use Puppet to configure an Apache server as frontend using the mod_proxy, without having to write a single Apache directive.

1 machine -> n servers

We often have the following topology: we use the same machine to host several systems. Let’s take, for example, a server used as a development forge and so hosting a maven repository manager, a continuous integration server, a code browser, a quality tracker, a source repository manager and so on. Another example is to host several web sites on the same machine. This is quite a common configuration for web sites that do not consume a lot of resources.

To route the request to the right web site, we set up an Apache frontend (aka proxy) redirecting the requests to the correct web site. The redirection is based on the target url, so for example http://my-site.com redirects to http://localhost:9015, or http://mydomain/nexus to http://localhost:9000.

An Apache server used as frontend

Configuring the Apache server to delegate the requests is not hard, once you have the required modules (mods) enabled, and are able to write Apache virtual host configurations (a mix between XML and plain text). But it starts to become rather cumbersome when the number of proxied sites or servers starts to grow, or when you need to replicate this configuration on another server.

By using Puppet for this purpose, we simplify the deployment of the system. Adding a web site will require 5 lines of code only. So in addition to all the other advantages of using Puppet and infrastructure-as-code, it also makes your Apache configuration cleaner.

Using Puppet to configure virtual hosts

There are a lot of Puppet modules to configure Apache. We chose one provided by puppetlabs, available on github. This module supports mod_proxy and mod_redirect out of the box.

So the first thing to do is to install the module. This module is hosted on the Puppet Module Forge, so can be installed using the puppet-module command:

puppet-module install puppetlabs-apache

Now that we have the module, we need to describe our system. With Puppet, you describe the resulting state and not how you reach it. So in our case we need to:

• ensure that Apache is available,
• ensure that the mod_proxy is enabled,
• define our virtual hosts

We can achieve these tasks with the following Puppet manifest:

Exec {
    path => ["/bin", "/sbin", "/usr/bin", "/usr/sbin"],
}

include apache

a2mod { "Enable proxy mod":
	name => "proxy",
	ensure => "present"
}

a2mod { "Enable proxy_http mod":
	name => "proxy_http",
	ensure => "present"
}

apache::vhost::proxy { "my-site":
	servername => "my-site.com",
	port => 80,
	dest => "http://localhost:9015",
	vhost_name => "my-site"
}

So, this manifest checks whether Apache 2 is installed and running correctly. Then, it ensures that the Proxy module and the Proxy module for HTTP are enabled. Finally, we declare our proxied site. The server name and the port indicates the address received by the Apache server that need to be redirected to the dest parameter. So in the previous example, we redirect http://my-site.com to http://location:9015.

Of course, we can declare several such proxied sites:

...
apache::vhost::proxy { "my-site":
	servername => "my-site.com",
	port => 80,
	dest => "http://localhost:9015",
	vhost_name => "my-site"
}

apache::vhost::proxy { "my-site-2":
	servername => "my-site-2.com",
	port => 80,
	dest => "http://localhost:9016",
	vhost_name => "my-site-2"
}

When we apply this manifest, all virtual hosts are created, and the Apache server restarted. So, we’re up and running.

One of the big advantages of Puppet is that you can add a virtual host, re-apply the configuration and it will set up everything for you. However, if the host is already defined, Puppet will do nothing: only new hosts are created.

Conclusion

This blog post has shown how Puppet can be used to create Apache virtual hosts to manage an Apache frontend delegating on proxied servers. If you’re running topologies such as the one described in this blog post, Puppet can help you to manage such configuration in a very elegant way.

Amazons virtual privacy cloud service (VPC) offers great outsourcing possibilities for your less private (but still private) services.

Consider a Jenkins build server. You have got one on your local machine but sometimes it’s just too much load for your hardware. It would be nice in such a case to just push some load into the cloud. Clearly you can not just put a Jenkins server into the cloud because it will need access to various services like at least some repository (Git, SVN). To protect that cloud-internal traffic (you do not want other Amazon customers to see your source code) one should use VPC. And for a seamless integration into your existing infrastructure you will need a VPN tunnel from the Amazon VPC to your local network.

Amazon offers the possibility to create such a VPN connection to your VPC. You may set up your own VPN server in your VPC but in our opinion it is easier and cheaper to use Amazons solution. Because it seemed less pricy we first tried to just use open-source software for that VPN server.

How Amazon builds up a VPN

Figure 1: Amazon’s VPN architecture

In figure 1 you see an overview of the VPN connection, how Amazon requires it. Let us say our VPN server has a public ip 1.2.3.4. For redundancy reasons amazon builds up two VPN tunnels with endpoint ip 87.238.85.40 for tunnel #1 and 87.238.85.44 for tunnel #2. You will need an ISAKMP daemon listening on your public ip 1.2.3.4 which will manage the two IPSec connections.

For each tunnel you need to set up an internal network device in the net 169.254.254.0/30 for tunnel #1 and 169.254.254.4/30 for tunnel #2. On Amazon’s side of each VPN tunnel there is a BGP router 169.254.254.1 for tunnel #1 and 169.254.254.5 for tunnel #2. From your internal ip for tunnel #1 169.254.254.2 you need to establish a BGP peering with that BGP router 169.254.254.1 and for tunnel #2 you need to do the same with the other two ips.

This is a route based VPN that means in our case any package that gets routed over the net 169.254.254.0/30 will use tunnel #1 and any packet that gets routed over 169.254.254.4/30 will be sent over tunnel #2.

So a packet from our internal net (let us say 192.168.1.0/24) which is addressed to our subnet in Amazon’s VPC (let us say 10.0.1.0/24) will get routed to one of the two BGP servers on Amazon’s side. To get there it will use the appropriate VPN tunnel and from the BGP server it will be sent to some Amazon-internal router. From there it will finally be delivered to our VPC. Sending a packet from the VPC to our home net is just the reverse way.

Amazon leaves no room for individual configuration. According to Amazons VPC-FAQ your device must be able to: (requirement list copied from there)

• Establish IKE Security Association using Pre-Shared Keys
• Establish IPsec Security Associations in Tunnel mode
• Utilize the AES 128-bit encryption function
• Utilize the SHA-1 hashing function
• Utilize Diffie-Hellman Perfect Forward Secrecy in “Group 2″ mode
• Establish Border Gateway Protocol (BGP) peerings
• Bind tunnels to logical interfaces (route-based VPN)
• Utilize IPsec Dead Peer Detection
• Perform packet fragmentation prior to encryption

Most points are supported by nearly all VPN servers that use IPSec for their tunnels. The most important points to look out for are:

• Establish Border Gateway Protocol (BGP) peerings
• Bind tunnels to logical interfaces (route-based VPN)
• Utilize IPsec Dead Peer Detection

Even if you look at the officially supported Cisco hardware like the Cisco ISR 880 series, you have to watch out for BGP support. Sometimes you need a software upgrade like (in case of the Cisco 880 series) the “Advanced IP Services”- upgrade. Whether a device or software supports route-based VPNs or not is oftenly not stated directly. You will have to look deeper into the manuals and descriptions to find out about that. If it just supports policy-based VPNs, it will not support route-based VPNs out of the box. Dead Peer Detection sometimes is not available on older devices (or software).

The Choice of VPN Servers

There is a list of officially supported VPN servers:

• Cisco ISR running Cisco IOS 12.4 (or later) software
• Juniper J-Series Service Router running JunOS 9.5 (or later) software
• Juniper SSG running ScreenOS 6.1, or 6.2 (or later) software
• Juniper ISG running ScreenOS 6.1, or 6.2 (or later) software
• Yamaha RTX1200 router

If you start using VPC you maybe just want to test it and do not want to spend much money for it (like for the above hardware). So it seems a good idea to use some linux box as VPN server. IPSec is implemented in the kernel and for ISAKMP you may want to use some daemon like racoon, Openswan, FreeS/WAN, or strongSwan.

Using Linux as VPN Server

Let us say you have decided to use some linux for your VPN server. For an IPSec newbie there is no obvious reason that this is a bad idea. And because one soon finds a tutorial like http://openfoo.org/blog/amazon_vpc_with_linux.html it seems possible to perform that task. Following this tutorial you should be able to ping the two BGP servers from your VPN server. And that means your IPSec tunnels are both up and working. But after that point you will start to get in trouble. Maybe you are able to connect to a server in your VPC. But there is one thing you won’t get working stable: Connecting from the VPC to some server in your home net 192.168.1.1/24. That is because linux has a policy-based IPSec implementation.

To connect your home net to the VPC net you need a policy like

spdadd 10.0.0.0/24 192.168.1.0/24 any -P in ipsec
    esp/tunnel/87.238.85.40-1.2.3.4/require;

If a packet from your VPC net gets routed over the tunnel #1 (over 87.238.85.40) everything
works fine. But if a packet from your VPC get’s routed over the other tunnel (over 87.238.85.44)
you’ve got a problem. Because you would need an additional policy like

spdadd 10.0.0.0/24 192.168.1.0/24 any -P in ipsec
    esp/tunnel/87.238.85.44-1.2.3.4/require;

to make your linux box unpack and forward that IPSec packet. That is a problem because you can not have two policies with the same source (here 10.0.0.0/24), destination (192.168.1.0/24), protocol (any), direction (in), and method (ipsec). This is why amazon requires a route-based VPN.

One workaround would be to connect just one tunnel. But this is not a good idea because you sacrifice the reliability of the VPN connection. As another workaround there are some dirty tricks to simulate a route-based VPN with Openswan (like http://lists.openswan.org/pipermail/users/2011-February/020123.html ). This, in our opinion, is not a good idea as well. This is because: First you need to use KLIPS (an older IPSec implementation) which has a rather bad reputation in the community. Second you need to apply a patch from some newsgroup. And the last and most important reason is that Openswan is not intended to be used that way. Abusing software in a security relevant place doesn’t seem to be a good idea.

Conclusion

There are two important things you won’t achieve going the linux-as-VPN-server way:

1. an easy to administer and supported solution
2. having a cost effective solution

The first point is because the linux IPSec implementation is not meant to be used for route-based VPNs. If it is possible, you’ll need some really dirty tricks. The second point is because for the officially supported devices Amazon offers generated configuration files. And these hardware routers are not as pricy as you think. For example a Cisco ISR 880 series CISCO881-SEC-K9 is available between 350-400€ (incl. VAT).

Our next step is to try an Amazon-supported solution. We will also post our experiences with that solution.

If you just want to try out VPC for a short time (like a few days) you may set up an OpenVPN server on a cloud instance in your VPC (and another OpenVPN server in youre home net). This solution will only cost less than the hardware solution if you are familiar with OpenVPN. This OpenVPN solution is only suitable for very small VPCs because you will need to adjust the routes on every instance inside the VPC manually.

However, organizing jobs on the CI server is not always easy.

This blog post describes a couple of strategies for creating dependent tasks with Jenkins (or Hudson).

On keeping things small

To make your continuous server really efficient for your team, you need to give feedback to your development team as fast as possible. After a commit (or a push), we all wait for a notification to make sure we didn’t introduce any obvious bugs (at some point, we’ve all forgotten to add a file to the SCM, or introduced a wrong import statement). However, builds tend to be long for enterprise applications; tests (both unit and smoke) can take hours to execute. So it’s imperative to reduce feedback time and therefore, to divide massive jobs into small and fast units.

For example, a regular build process would generally take the following actions (for each module/component):

• compile the code
• run unit tests
• package the code
• run integration tests
• extract quality metric
• generate reports and documentation
• deploy the package on a server

It’s clear that carrying out all those tasks on a multi-module project can take a considerable length of time, leaving the development team waiting before they can switch to the next task. It’s not rare to see a Maven build taking (just for the compilation / test / packaging) up to 30 minutes.

Moreover, smaller jobs offer much more flexibility. For example, one can restart from a failing step without restarting the full build from scratch.

A true story : Restarting a test server

Recently, in one of our projects, we had to clean up and re-populate a test server. In the first version, a script was executing the following actions in one massive job:

• Stop the server
• Clean up the file system
• Drop tables
• Create tables and populate with test data
• Start the server

The process was taking more or less 10 minutes, and in case of failure didn’t allow restarts from the failing step.

In a second version, each action was executed in its own job. However, jobs were not dependent on each other, which required job/wait cycles of 10 minutes.

Jobs to achieve our second scenario

Finally, we linked jobs together to trigger the whole process by simply starting the first job. To create those dependencies, we tried three approaches of which two were successful (I’ll let you guess about the third one).

One-to-One Relationship

The first approach was pretty simple: one job triggers another one after successful completion. So in our case:

Stop server
    |-> Clean up filesystem
           |-> Drop database
                  |-> Create table and insert data
                        |-> Start server

INFO: Pipeline Blog Post - Stop Server #3 main build action completed: SUCCESS
07.11.2011 15:12:20 hudson.model.Run run
INFO: Pipeline Blog Post - Cleanup #3 main build action completed: SUCCESS
07.11.2011 15:15:27 hudson.model.Run run
INFO: Pipeline Blog Post - Dropping tables #3 main build action 
completed: SUCCESS
07.11.2011 15:17:29 hudson.model.Run run
INFO: Pipeline Blog Post - Creating tables and Inserting data #3 main build action completed: SUCCESS
07.11.2011 15:22:31 hudson.model.Run run
INFO: Pipeline Blog Post - Start server #3 main build action completed: SUCCESS

To achieve these sorts of relationships with Jenkins, you can either configure a post-build action starting the next job (downstream) or configure the trigger of the current build (upstream). Both ways are totally equivalent.

Triggering a job after successful completion of the current job

This first way is probably the most intuitive. It consists of configuring the job triggered after the current job. In our scenario, the ‘stop server’ job triggers, on successful completion, the ‘cleanup’ job. To configure this dependency, we configure a post-build action in the Configure page of the ‘stop server’ job:

Trigger a build once the current job finishes

Starting the current job after completion of another build

With this second way, you configure which job triggers the current job. In our scenario, the ‘cleanup’ job is triggered after the ‘stop server’ job. So in the Configure page of ‘cleanup’, in the Build trigger section, we select the Build after other projects are built and specify the ‘stop server’ job:

Using this one-to-one dependency approach is probably the simplest way to orchestrate jobs on Jenkins. With such easy configuration, decomposing complex activities / build processes is very simple. You can restart the stream from any point, and get feedback after every success or failure.

Über Job: the wrong good idea

One attempt to optimize the previous method was to create a kind of über job, triggering all other jobs. Unfortunately, even if it was a brilliant idea on paper, it doesn’t work. Indeed, there are two issues:

• Even if a job fails, others are triggered
• The job execution order is not deterministic

The first point is simple to explain: the jobs are not interconnected, so even if one fails, others are still executed. This can be really annoying if the initial requirement of a job is not set up correctly.

07.11.2011 15:32:51 hudson.model.Run run
INFO: Pipeline Blog Post - Uber Job #6 main build action completed: SUCCESS
07.11.2011 15:32:59 hudson.model.Run run
INFO: Pipeline Blog Post - Stop Server #5 main build action completed: SUCCESS
07.11.2011 15:33:01 hudson.model.Run run
INFO: Pipeline Blog Post - Cleanup #3 main build action completed: SUCCESS
07.11.2011 15:33:03 hudson.model.Run run
INFO: Pipeline Blog Post - Dropping tables #3 main build action completed: FAILURE
07.11.2011 15:33:05 hudson.model.Run run
INFO: Pipeline Blog Post - Creating tables and Inserting data #3 main build action completed: SUCCESS
07.11.2011 15:33:07 hudson.model.Run run
INFO: Pipeline Blog Post - Start server #3 main build action completed: SUCCESS

In this log, the ‘drop tables’ job failed. We would expect the whole scenario to come to a halt at this point, but unfortunately that’s not the case. When this happens, we can’t be sure of the resulting state on our restarted server.

The second point is more tricky. Jenkins is built on an asynchronous model: jobs are scheduled and will be executed later. The order of execution can depend on a lot of different parameters, so the order is hard to plan. In our case, we have seen:

07.11.2011 15:32:51 hudson.model.Run run
INFO: Pipeline Blog Post - Pipeline #18 main build action completed: SUCCESS
07.11.2011 15:32:59 hudson.model.Run run
INFO: Pipeline Blog Post - Stop Server #15 main build action completed: SUCCESS
07.11.2011 15:33:01 hudson.model.Run run
INFO: Pipeline Blog Post - Cleanup #13 main build action completed: SUCCESS
07.11.2011 15:33:03 hudson.model.Run run
INFO: Pipeline Blog Post - Creating tables and Inserting data #13 main build action completed: SUCCESS
07.11.2011 15:33:05 hudson.model.Run run
INFO: Pipeline Blog Post - Dropping tables #13 main build action completed: SUCCESS
07.11.2011 15:33:07 hudson.model.Run run
INFO: Pipeline Blog Post - Start server #13 main build action completed: SUCCESS

You can see that the tables were dropped after the data was inserted. Well… I’ll let you guess the state of the server after this execution.

So, even if this method seemed to be a good idea, it’s actually a pretty bad idea if you want your process executed reliably.

A bit of optimization: Fork and Join

This last method uses a Jenkins plugin named ‘Join plugin’ (see the Join plugin page). In brief, this plugin allows you to configure fork/join patterns: once downstream projects are completed, other projects are triggered.

If you have jobs that can be run in any order, this plugin will reduce the amount of configuration you need. In our scenario, in the ‘stop server’ job, it can be used as follows:

So, the ‘stop server’ job triggers the ‘clean up’ and ‘drop table’ jobs. Once those (independent) jobs are completed, we trigger the data insertion and restart the server. In our experience, these two ‘join’ jobs were always executed in right order (and on the same executor). But we recommend triggering only one join job with a one-to-one dependency:

            /-> Cleanup    -\
    Stop server              * ->  Insert data -> Start server
            \-> Drop table -/

This approach reduces the number of builds to configure, but should be used only if your jobs are independent.

A last tip

Especially in the one-to-one approach, the pipeline can become pretty long. Jenkins has a nice plugin to visualize the downstream builds: Downstream buildview plugin.

We recommend using this plugin to track the progress and visualize the result of complex/long pipelines.

Conclusion

Even if the advantages of splitting a long build process into small jobs are obvious, doing so may be more difficult than expected. This post has presented several ways to create dependencies between your jobs for Jenkins/Hudson.

Apache Maven is a widely used build tool adopted by more and more companies to support their build process from compilation to deployment. Deploying, in the  Maven world,  means uploading the artifact to a Maven repository. Such Maven repositories are managed using Sonatype Nexus or JFrog Artifactory. However, this sort of deployment does not address the real provisioning of the application, i.e the deployment on the production servers.

This blog post presents a Puppet module to download Maven artifacts from a Nexus repository. This module closes the gap between the development team deploying their artifacts to a Maven repository, and the administration team responsible for installing and configuring the application.

Why use Puppet to download Maven artifacts ?

The first question you’re probably wondering is “why?”. At akquinet, Apache Maven and Nexus are cornerstones of our build processes. However, dealing with the live deployment still requires manual configuration, copies and so on. This process is error-prone and puts a lot of pressure on the development team. So, we started adopting Continuous Delivery and Infrastructure as Code to improve this last deployment step. But, all our applications and artifacts were stored in Nexus repositories, and the deployment to the production servers requires copying them onto a different type of server (generally via SSH/SCP) to be then deployed to the production servers. Even if these copies were automated using a continuous integration server (such as Jenkins), we’re duplicating the artifacts, making harder to trace the origin of each file. So, it makes a lot of sense to avoid this second server and to retrieve the artifacts directly from Nexus.

The puppet-nexus module is a Puppet extension downloading Maven artifacts from Nexus. Why Nexus? Because it relies on the REST API of Nexus. This Puppet extension supports authentication and repository selection. Actually, we have developed a Bash script to do the job. This script can be used outside of the Puppet module and is just wrapped inside Puppet. But we needed a solution integrated with Puppet and our deployment tool, and which simplified usage of the script.

The Puppet Nexus Module

The Puppet Nexus module defines two entities: The Nexus class and the artifact resource.

The Nexus class is configured with the base url of your Nexus installation and the credentials of the user:

class {'nexus':
    url      => "http://edge.spree.de/nexus",
    username => "nexus",
    password => "********"
}

Once done, you can declare nexus::artifacts as follows:

nexus::artifact {'commons-io':
   gav        => "commons-io:commons-io:2.1",
   repository => "public",
   output     => "/tmp/commons-io-2.1.jar"
}

The artifact is identified using the GAV coordinates (groupId:artifactId:version). The module supports SNAPSHOT versions (downloading the latest snapshot). The classifier and packaging attributes allow you to select the right file:

nexus::artifact {'chameleon web distribution':
   gav        => "org.ow2.chameleon:distribution-web:0.3.0-SNAPSHOT",
   classifier => 'distribution',
   packaging  => 'zip',
   repository => "public-snapshots",
   output     => "/tmp/distribution-web-0.3.0-SNAPSHOT.zip"

The repository attribute indicates the repository to use, generally a group (i.e. a group of proxies and hosted repositories) such as the public, public-snapshots, central. Check your nexus installation to know which repository you should use.

The output attribute indicates the location of the downloaded artifact. It must be an absolute path (following the Puppet convention).

The ensure parameter can be set to:

• present : does not update the file if already there
• absent : deletes the file if there
• update : updates the file (default)

# Checks that the file is present, downloads it if needed
nexus::artifact {'ipojo-2':
    gav        => "org.apache.felix:org.apache.felix.ipojo:1.8.0",
    repository => "public",
    output     => "/tmp/ipojo-1.8.jar",
    ensure     => present
}
# Delete the file
nexus::artifact {'ipojo-1':
    gav        => "org.apache.felix:org.apache.felix.ipojo:1.8.0",
    repository => "public",
    output     => "/tmp/ipojo-1.8.jar",
    ensure     => absent
}
# Update the file
nexus::artifact {'ipojo-3':
    gav        => "org.apache.felix:org.apache.felix.ipojo:1.8.0",
    repository => "public",
    output     => "/tmp/ipojo-1.8.jar",
    ensure     => update
}

Getting and using the module

To use the presented module, clone the git repository. Once done, configure the modulepath of Puppet in the Puppet configuration file (/etc/puppet/puppet.conf). Once the module is installed correctly, you can download any Maven artifacts from the repositories hosted on your Nexus instance as presented above.

The common pattern is to download an archive containing your application (EAR, ZIP, WAR) and to unzip it (if needed) to the right location such as in the deploy folder of your application server.

Conclusion

This blog post has presented a Puppet Module closing the gap between Maven deployment and the production installation. The Nexus Puppet Module allows you to download Maven artifacts on your production servers. Artifacts are still organized and managed by Nexus. They are downloaded when the application is installed using Puppet.

On the other side, Play framework is a promoting a new way to build web applications, making this sort of development more efficient and productive. By avoiding the turn over (compilation-packaging-deployment-navigation) after every change, it makes web development fun again.

This blog post explains how you can deploy your Play applications using Puppet. This allows you to develop web apps in a very productive way and deploy them reliably.

Treat your infrastructure as code

Infrastructure-as-code is a major trend in IT management. It aims to make infrastructure configuration more traceable and understandable. You can summarize this movement as “Treat your infrastructure as code. Programmable. Testable. Deployable”.

There are a couple of tools to help you make your infrastructure as code such as Chef, Vagrant and Puppet. There are already plenty of resources to compare them. In this blog post, we use Puppet.

Puppet is an open source configuration manager tool. Puppet follows one important philosophy: you describe what not how. In other words, you describe the resulting state and not how to reach it. This description is stored in a manifest specifying resources and desired states. Puppet discovers the system information and compiles the manifests into a system-specific catalog containing resources and resource dependency which is applied against the target systems. Any actions taken to remediate the system to the desired state will be reported.

In Puppet, everything is a resource. So, to support Play applications, we just have to define new resources.

Playing with resources

To support the provisioning of the Play framework and of Play applications, we wrote a Puppet module (available here) for Ubuntu, defining three resources: module, application and service.

But, before looking into those resources, let’s have a look at the Play class initializing the Play framework support. This class simply checks the availability of the Play framework on the target system and if not available, downloads and installs it.

So now that we’re sure that Play will be installed, let’s look at our resources.

• play::module handles a Play module. So this resource ensures the availability of a specified module. If not present, it installs the module.
• play::application handles a Play application. It ensures that the specified Play application is running (or stopped). If needed it starts (or stops) it. In case of starting, it resolves the dependencies. This resource supports the framework id, as well as JVM options.
• play::service handles a Play application started as a service. It ensures that a daemon script is present in /etc/init.d and is started. Similarly to play::application, it supports framework id and JVM options.

Less conversation, more action Please

Ok, enough talk; let’s see how you can deploy Play applications in practice. First, you need an Ubuntu server with Puppet, git and Java installed. Everything except Puppet can be installed with Puppet.
You can choose to install the Puppet module in /etc/puppet/modules or in any other directory. For that, just clone the Play Puppet Module:

git clone git://github.com/cescoffier/puppet-play.git play

Check that your Puppet Module path included the chosen module directory (in /etc/puppet/puppet.conf), or declare the modulepath parameter when launching Puppet.

The Puppet module does not define how your application is copied/delivered on your host. You can achieve it using scp, wget or even git. Just choose your preferred way. We just assume that we have our application copied in /var/data-www/bilderverwaltung.

Now, let’s have a look at our manifest, generally named site.pp:

Exec {
    path => ["/bin", "/sbin", "/usr/bin", "/usr/sbin"],
}
# Install mongoDB
include mongodb
#Install Play and define our Play service
include play
play::module {"mongodb module" :
 	module => "mongo-1.3",
	require => [Class["play"], Class["mongodb"]]
}
play::module { "less module" :
 	module => "less-0.3",
	require => Class["play"]
}
play::application { "bilderverwaltung" :
	path => "/var/data-www/bilderverwaltung ",
	require => [Play::Module["mongodb module"], Play::Module["less module"]
}

This manifest installs mongodb, defines two Play modules (less and mongodb), and starts the Play application. The require relationships are used to orchestrate the resolution of resources, i.e. first the Play framework, then the modules and finally the application.

So, if you apply this manifest, it installs the Play framework, installs the two modules, and starts your application:

sudo puppet apply --modulepath=/my/puppet/modules site.pp

That’s it. Thanks to Puppet, all the tricky configuration parts are managed for you. So just store your manifest in a source code management repository, and you can trace changes, rollback and re-apply the same manifest on different servers. You can also use the Play module in a Puppet master-client configuration to configure and manage sophisticated infrastructure. You can also enhance the manifest to configure an Apache 2 virtual host, or whatever you need.

Conclusion

This blog post has briefly introduced the advantage of using infrastructure as code and how you can manage Play applications with Puppet. The Play module web site contains more details about the module and the different resources.

The OSGi Helper library was developed by the Innovation department of akquinet, and was contributed to the OW2 Chameleon project.

This post explains the benefits brought by the library in comparison to plain OSGi tests.

Plain OSGi testing

Let’s imagine the well-known Hello Service:

public interface HelloService {
    public String sayHello();
    public String sayHello(String name);
}

Let’s also imagine a really great implementation:

@Component
@Provides
@Instantiate
public class HelloServiceImpl implements HelloService {

    public String sayHello() {
        return "hello";
    }

    public String sayHello(String name) {
        return "hello " + name;
    }
}

This implementation is using the Apache Felix iPOJO component model, but you can imagine any other development model such as plain OSGi, SCR or Blueprint.

Now that we have our application, let’s look at a simple OSGi test for our Hello Service:

@Test
public void testWithoutHelpers() throws Exception {
    HelloService service = null;
    ServiceReference ref = null;
    for (int i = 0; service == null  && i < 10; i++) {
        ref = context
            .getServiceReference(
               HelloService.class.getName());
        if (ref == null) {
            // Wait until the service is there...
            Thread.sleep(10);
        } else {
            service = (HelloService) 
                context.getService(ref);
        }
    }

    Assert.assertNotNull(service);

    // We have the service object, run the test
    Assert.assertEquals("hello", service.sayHello());
    Assert.assertEquals("hello John", 
               service.sayHello("John"));

    context.ungetService(ref);
}

The above code uses Pax Exam, but the code would be pretty much the same if you use another testing framework.
Notice that this test contains more OSGi code than functional test.

Using the OSGi Helper Library

Let’s now see how our test looks like when using the library:

@Test
public void testWithHelpers() throws Exception {
    HelloService service = helper.waitForService(HelloService.class, null, 1000);
    Assert.assertEquals("hello", service.sayHello());
    Assert.assertEquals("hello John", service.sayHello("John"));
}

Thanks to the OSGi Helper, the test method focuses only on the functional behavior. The waitForService method is looking for the service. If the service is not available before the given timeout (in milliseconds), the test fails. Thanks to this simple method, getting the service to test is definitely simpler. Moreover, you don’t need to release the service. The OSGi helper does it for you.

OSGi Assertions

The OSGi Helper library also provides a couple of assertions to check the OSGi aspect of the application (deployed bundles, available services…). The following method gives you a short overview of such assertions:

@Test
public void testWithAssertions() throws Exception {
    OSGiAssert assertions = new OSGiAssert(context);

    assertions.assertServiceAvailable(HelloService.class, 1000);

    assertions.assertBundlePresent("hello-service-impl");
    Bundle bundle = helper.getBundle("hello-service-impl");
    bundle.stop();
    assertions
        .assertBundleState("hello-service-impl", Bundle.RESOLVED);

    assertions.assertServiceUnavailable(HelloService.class);

    bundle.start();
    assertions
        .assertBundleState("hello-service-impl", Bundle.ACTIVE);
    assertions.assertServiceAvailable(HelloService.class, 1000);
}

Conclusion

This blog post has presented a brief overview of the OSGi Helper library. This library contains more good stuff to test OSGi and iPOJO applications.
The code of this blog post is available from Github.

The OSGi Helper library was developed by the Innovation team of akquinet in order to improve the testability and the quality of OSGi applications. The library is now part of the OW2 Chameleon project and delivered under the Apache License 2.0.