Skip navigation
All Places > Alfresco Content Services (ECM) > Blog > Authors slanglois

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!

'When are you moving to Git/GitHub/Bitbucket/decentralised version control software/...' must be the most frequent question I get, both from people inside and outside of Alfresco.

I usually start by explaining that Alfresco is on GitHub! The Alfresco organisation there currently owns 35 public repositories, and many of them are very active. All our mobile code has been there forever; for instance: (iOS + Android) * (SDK + App), as well as Aikau, Gytheio, the Alfresco SDK, etc. The recent announcement that Google Code is going to shut down triggered another batch of migrations to GitHub, such as Jive Toolkit, dropbox integration, and more.


Of course, what the question really means is: 'When is the Alfresco Platform codebase moving? Not some petty integration or client app.' :-) Well, we do have a mirror of the Community Edition source on GitHub. But as for moving the whole code base there, the answer is: never -- at least in its current form. Here are a few reasons why.

    • It doesn't fit!

      GitHub has a limit of 1GB per repository. We hit that limit for the mirror, and had to filter a few big folders. (Even Linux had to cut down the history of the repository to move there!) Of course, we used to commit big jar files in the source. We don't any more, but even then, we still cross the limit. And it's not just GitHub but all DVCS: holding all the history of the repository in your local copy has a big impact if you have a 10 year old code base of one million lines of code!

 

    • Continuity with past releases

      We could make a clean cut, leaving the Old World in Subversion and having the Brave New World in Git. That would work, but it would make merging modifications from earlier maintenance branches very hard -- and most of our commits are of that kind! We have 4 active service pack branches (4.1.x, 4.2.x, 5.0.x) and 18 active hotfix branches (from 3.4.14.x to 5.0.1.x) All fixes have to be merged forward, so that people don't get regressions when upgrading. Doing this is tedious enough without having to switch software in the middle!

 

    • Access rights

      Our Subversion repository is currently a patchwork of access rights, and DVCS don't support that -- the idea being that you spread your software in smaller repositories, and manage the rights for each repository. Even in a given branch, we have folders which are public (Community Edition), others which are reserved to customers (Enterprise Edition) and others which are private (Cloud Edition).

 

    • Big team, big problems

      I don't want to manage a Git repository where 50 people (and counting!) commit daily. DVCS are inherently more complicated than centralised systems (think of what identifies a revision, for instance), which certainly allows for more power, but also more headaches in big teams where not everyone has a PhD in Gitology!


However, don't despair. We are not stuck in this situation forever! As you saw earlier this week, we are currently working hard to make the code more modular, and to extract from our big codebase some independent, consistent pieces that can be released separately. You've seen this already with Aikau and Share (but it also happened a while ago with Records Management, and all the integrations).

As we extract smaller chunks, it can make sense to move them over to GitHub, because they will then be more manageable and will have a small team of people responsible for it. The goal here is twofold: externally, to release more frequently to our audience, and internally, to allow more parallel developments to happen and be more agile.

I hope you are as excited as we are about this change - this is much more interesting than just changing our SCM software!

Well, this was a long journey, but we are finally getting there! As was already announced, Alfresco Community is now built with Maven, and so will the next version of Alfresco One. We thought we would tell you a bit more about it.

Achievements unlocked 

Alfresco is a BIG piece of software, and building it is not simple. There are several editions (Community, Enterprise, Cloud), several code generation steps, a huge number of external dependencies, etc. Also, a lot of quirks had accumulated in the Ant build over the years, as they do...
We couldn't just stop releasing for the few months while we did the migration. The difficult part was thus to make it progressive! Here are the steps we took
    • June 2012: Deploying Alfresco artifacts to a Maven Repository
      This was a popular request by customers and partners, who were already using Maven or Gradle. Gabriele Columbro had already started the job. We extracted the jars and wars of all past releases and uploaded them to http://artifacts.alfresco.com/
    • November 2012: Adding dependency declarations
      Initially, the pom.xml files for these artifacts were empty. With Alfresco 4.1.2, we started writing and providing POM files that defined the dependencies, both between Alfresco artifacts and with 3rd party libraries. This was also the start of the parallel build: the same code was built in both Ant and Maven in our continuous integration, to make sure the POM files were correct.
    • July 2013: Separating test classes
      A big problem was that the main and test classes were mixed in the same source folders. Mao had find a nice hack to overcome that, by recreating a Maven standard layout on the fly in the target folder! But a complete separation was overdue, and we finally did it for Alfresco 4.2
    • December 2013: MyAlfresco built with Maven
      This happened under the hood. We had decided that the build of the Cloud version my.alfresco.com would be easier to switch to Maven: it only needs to support one platform, and the artifacts to build are much simpler. At the end of the year, the Maven build was deemed good enough to be put in production.
    • February 2014: Separating unit tests from integration tests
      This was mostly the work  of Gethin James, who was tired of typing -DskipTests... The default Maven build now fires only unit tests, so there is no need to worry about configuring the database or waiting for hours: Just type mvn clean install :-)

 

Changes on your side

If you depend on Alfresco artifacts coming from the Maven Repository, then you will have to change a few things to your builds. Hopefully not too much...

 

First, the infamous classifier=config artifacts, which contained the resources of each jar file, have now gone. The resources are contained in the jar, as is standard in most places. If you depend on such artifacts, just remove them from your dependencies.

 

Second, the packaging of solr has changed. Instead of providing a zip that contains everything, we are again now conforming to the standard, and so alfresco-solr is simply a war file, which comes with its jar of classes (classifier=classes). Yes, and another artifact that contains the configuration (classifier=config), which should be unzipped on top of it if you need to run Solr.

 

At last, alfresco-mmt is now a standalone executable jar, rather than a small jar with dependencies on third-party libraries, for convenience

 

A new version of the Maven SDK is on its way, which will support Alfresco 5.0, along with a few added goodies. Thank you Ole Hejlskov for your help with it!

 

What now?

The Enterprise version of Alfresco still requires a bit of work. This will be the last step before we can remove the Ant build completely - including all these annoying committed libraries!

Finally, there are most certainly a few remaining issues: missing artifacts, packaging mistakes, regressions, etc. Please tell us if you find anything!

 

You can now download Alfresco Community 5.0.a Its artifacts are of course in our Maven Repository. The version of Alfresco is now 5.0.a, and 5.0.b-SNAPSHOT for the nightly builds. We will keep the Ant-built 4.3.a-SNAPSHOT artifacts in the Maven repository for a while, to help the transition.

 

Thank you for your support in making it happen! We hope you are just as pleased as we are :-)

Filter Blog

By date: By tag: