slanglois

Separating Platform and Share in Alfresco 5.1

Blog Post created by slanglois on May 27, 2016

The content of this post is mostly based on the talk I gave at the amazing BeeCon 2016 conference, in Brussels.

Alfresco One 5.1, released in March 2016, introduced a separation in the packaging between Alfresco One Platform and Alfresco One Share. I want to explain a bit behind the motivations for this; how we did it and what's in it for you.

Why separate?


The main reason was to have different release lifecycles between Platform and Share. That means we can now, for instance, release versions of Share more often, without having to retest the whole Platform (which is very costly with all the databases, application servers, etc.)

The releases are also smaller and more incremental. We hope it makes it easier to upgrade the Platform while keeping a heavily modified Share: this seems to be a common use case!

From a more 'Alfresco Engineering' point-of-view, there are more reasons to split: the combined codebase was huge, and we couldn't really assign it to a single team. Now, we have reorganised our teams, and we have proper Platform and Share teams, each taking responsibility for their own codebase. Ownership is simpler, the issue backlog is smaller, and we are overall more agile.

Where to cut?


We needed to decide where to draw the line between Platform and Share code.

An initial idea was to create one codebase for each artifact (jar or war): alfresco-core.jar, alfresco-data-model.jar, etc. But that would have been a bit too many to handle.

The most obvious was to simply cut between the two war files: alfresco.war and share.war. However, that meant that we couldn't update the Share APIs (webscripts, etc.) when we update Share, since they are actually delivered in alfresco.war.

We got inspiration from this blog post from Netflix. The idea is explained in this picture, which I have shamelessly reused here:

Slide04

Netflix has to support a lot of very different devices: browsers, Wii, XBox, iPhones, ...

To add some flexibility to their server-side code, they created this notion of Client Adapter Code. It is delivered at the same time as the client, but actually sits on the server-side, allowing each client to evolve and manage their own API within their own lifecycle. This is exactly what we needed!

The Share codebase therefore produces a Platform-side component, called Share Services, which is packaged as an AMP. It contains the /slingshot webscripts, the sample site bootstrap, and the datalist and wiki services. The alfresco-share-services.amp is applied to alfresco.war: its source is in Share, but it runs in the Platform.

SeparatingShare-shareservices

Separating common pieces


Some components are used by both Platform and Share. We needed to separate each of them into their own codebase too, otherwise we couldn't release Share without releasing Platform. So we extracted these components, and now they have their own lifecycle:

       
    • alfresco-core  (which should really be called alfresco-common as it's a set of utility classes.)
       
    • JLan (our implementation of the CIFS protocol)

 


All these are kept in the same Subversion server. This is much more convenient when we need to merge fixes from old branches to and from 5.1. We may move these to Git in the future.

Of course, we also had to cut a few cyclic dependencies, but it wasn't too bad...

What do we package?

Community Edition


We had discussions on whether we should provide Platform and Share packages for the Community Edition. We decided not to, because Community is typically used on single node installations. Also, it's quite often an entry point for people researching Alfresco, so we wanted to keep things simple there. (I had people complaining about this at BeeCon, but I'm still looking for a valid use case...)

Since it will contain components with different versions, we had to find a different versioning convention. We settled on a version based on the year and month: 201605. We also add a -GA (General Availability) or -EA (Early Access) suffix, to make clear the level of testing it had. For instance, the latest version of Community is called 201605-GA, and it contains:

       
    • Alfresco Platform 5.1.g (a security issue fix from 5.1.f)

 

    • Alfresco Share 5.1.f

 

    • GoogleDocs integration 3.0.3

 

    • Alfresco Office Services 1.1


Share separation does benefit Community Edition though, because we can ship more often, and include only what has changed, as with 201605-GA

Enterprise Edition


For clusters and complex setups, as supported by Alfresco One, it is useful to install Platform and Share separately, so we have provided separate installers for each of them. The Share one installs a separate Tomcat instance and just deploys share.war in it. It also copies the Share Services AMP into the installation folder, but you will need to apply it yourself to the Platform installation it connects to - see the documentation.

We thought a 'full' installer, with both Platform and Share, was still needed. It is convenient for people who want to try Alfresco without knowing much about its architecture, or simply for standalone instances. The version of this all-in-one installer for Alfresco One still reflects the version number of the Platform, i.e. 5.1. We are waiting to see what people think of the Community Edition naming before we change the naming for Alfresco One.

In summary, here are the different packages we offer for the Enterprise Edition:

SeparatingShare-overview

What next?


We didn't go as far as we had planned. For 5.1.x, the source codebases are separated, but we are still going to release Platform and Share at the same time, with the same version number. We lacked time to test each component individually. Previously, Alfresco could be tested as a whole and it was fine. For instance, JLan was mostly tested by integration tests in the Platform. Now, we need to make sure JLan works on its own, before we release it, because we may have to release it just for a Share version, without running the Platform tests against it.

We also didn't think we could ensure that Platform 5.1.X would work with Share 5.1.Y - once again due to the lack of tests and of clear public APIs between the components. (Although this improved in 5.1 – see the BCK project for instance, or the documentation on extension points.)

In the near future, we are planning to separate more components from the Platform. The most likely candidates are currently:
 

    • Search, as part of the upgrade to Solr 6
       
    • More of Share: there are parts of the Platform that we think should belong to Share, such as calendars, blogs, ... And we still want to release it separately in the future!
       
    • Enterprise extensions, to upgrade from a Community Edition


I'm not making promises of course, but this is on the roadmap, so it looks good!

Outcomes