Skip navigation
All Places > Alfresco Content Services (ECM) > Blog > 2015 > May

chef-alfresco has a new home!

Posted by mpillitu May 22, 2015

Important Disclaimer!
Chef-alfresco is part of the Alfresco Community offering thus is not supported.

It is not guaranteed to work and we are not accountable for any problem it may cause in your running environments.
You can use it at your own risk and you are welcome to help the testing and development by reporting issues

After 30 months of development and 30 releases, chef-alfresco have been moved under the Alfresco umbrella; if you want to have an overview of Alfresco deployment challenges, you can checkout the presentation at Summit 2014

As part of the Alfresco Devops team, I have been working on chef-alfresco project, aiming at the following high-level goals:

    • Easy to use deployment tool that can be simple to test by (Chef) users

    • Extended library of deployment tools that can be used either to create immutable images or to perform installations on pre-existing environments

    • Tested against CentOS platform (apologies to Ubuntu users for possible regressions from previous versions)

    • Feature-rich, covering the most frequent Community and Enterprise installation use-cases

To give you an idea of chef-alfresco features, here's the complete list of components you can use right now:

    • tomcat: installs Apache Tomcat; it supports single or multi-homed installation

    • repo: installs and configures Alfresco Repository webapp and all its related plugins

    • transform: installs all 3rd party software needed by Alfresco (swftools, libreoffice, imagemagick, OS fonts)

    • share: installs and configures Alfresco Share webapp and all its related plugins

    • solr: installs and configures Alfresco Solr webapp

    • haproxy: installs Haproxy and configures it to proxy Tomcat instance(s) to /share and /alfresco paths

    • nginx: installs Nginx and configures it to proxy Haproxy and apply SSL Offloading

    • mysql: installs and configures a MySQL server local instance. It also creates database and user to run Alfresco against it

    • rm: installs Alfresco Records Management extension (AMP)

    • googledocs: installs Alfresco GoogleDocs extension (AMP)

    • aos: installs and configures Alfresco Office Services (enterprise-only)

And this is the direction we want to take in the short-mid term:

    • media-management integration (MUST)

    • reporting&analytics integration (MUST)

    • postgresql integration (SHOULD)

    • Ubuntu compatibility (COULD)

    • Windows compatibility (WOULD)

In the long term we aim to contribute chef-alfresco to Chef Supermarket.

Are you using Chef to deploy Alfresco? We would love to hear from you how to improve chef-alfresco and meet your needs; just drop a comment here or open issues.



Alfresco Share has supported themes in general for some time, but it is more challenging to customize the colours used in the Share header bar. We've made some updates in the Aikau 1.0.18 release that now make this a much simpler process. You'll be able to take advantage of these in either Alfresco Community 5.0.d or Alfresco Enterprise 5.0.1 if you upgrade the default version of Aikau used, but will be available for use out-of-the-box in Alfresco Enterprise 5.0.2 and future Community releases. This blog post will explain how to create or update a Surf theme to customize the header colours, as well as providing some context on why it has taken so long to provide this capability and the ways in which it will further improve in the future.


A Bit of History...

The current widgets used for the Share header were created during the 4.2 release. At that time we were experimenting with ways in which we could improve theme handling but it wasn't until after the 4.2 release that we included dynamic LESS pre-processing into Surf page rendering.


Although there was an effort to generate some momentum in updating the Share themes it wasn't really a priority at the time and as a result the capabilities that were introduced weren't made use of in the 5.0 release.


It's only now that 5.0 is starting to get some focus in the field that we've started to see questions related to this particular type of customization. It has always been possible to change the header colours by modifying the CSS files directly or replacing them completely, but with the release of Aikau 1.0.18 we've gone back through the “alfresco/header” packaged widgets and updated the CSS files to make use of some new LESS variables.


LESS and Themes

Overriding the default LESS variables (which are defined in defaults.less in Aikau and included for every theme) is currently done by adding a particular element to the Surf Theme XML file. I appreciate that it's not ideal to be writing LESS in an XML file but there are historical reasons for this and in the future I hope to be able to change this so that the Theme XML file can reference one or more LESS files as required.


A Surf Theme is defined by an XML file that lives in the “themes” subfolder of the client’s Surf configuration folder, in Share this can be found in “share/WEB-INF/classes/alfresco/site-data/themes”. If you want to create a new theme for Share that supports the legacy YUI2 widgets you should also create a theme folder with a name that matches your Surf Theme name – if working with a standalone Aikau client (e.g. one created by the Aikau Maven Archetype) then this isn't necessary.


In the theme XML file include the following within the <theme> element:



Within the <less-variables> element you can place any valid LESS content ( If we want to override the LESS variables for the header we can add the following content that results in an awesomely garish header:

@header-background-color: #0082c8;
@header-font-color: #ccc;
@header-hover-background-color: orange;
@header-hover-font-color: green;
@header-focus-background-color: yellow;
@header-focus-font-color: red;
@header-menubar-font-color: pink;
@header-dropdown-menu-font-color: purple;


The resulting customized header


Variable Breakdown

We've tried to make the LESS variables as semantically meaningful as possible, but in case it's not obvious I'll break down what each variable does.

    • @header-background-color - This is the main background color for the header (e.g. in Share this is black)
    • @header-font-color - This is the colour of fonts when menus are neither hovered or focused, in Share this is a light grey colour by default.
    • @header-hover-background-color - This is used for the background colour of the header menu widgets when the mouse hovers over them. In Share this is a light grey colour.
    • @header-hover-font-color - This is used as the colour of the header menu widgets when the mouse is hovered over them
    • @header-focus-background-color - This is the background colour of the header menu widgets when they have focus, therefore it is also used as the background colour of drop-down menus (as they have focus when opened). In Share this is a darker grey colour by default.
    • @header-focus-font-color - This is used as the font colour of focused header menu widgets. So it is used as the font colour of items in opened drop-down menus. In Share this is white by default
    • @header-menubar-font-color - This is used as the font colour of menu bar items (e.g. not drop-down menu items). In Share this is the darker grey by default.
    • @header-dropdown-menu-font-color - This is used as the font colour of drop-down menu items. In Share this is white by default.

Editing the Green Theme in Share  


If you look through the defaults.less file in Aikau you'll see that there are lots of other LESS variables that you can override. Although not all of the widget CSS files make use of these LESS variables we are going to endeavour to improve this over future releases. However, if there are any widgets in particular that you wish were easier to customize then please let us know – it's very difficult for us to support use cases that we don't know about, so please let us know by raising issues on GitHub or JIRA.

Aikau Update, May 2015

Posted by ddraper May 12, 2015


I've been pretty quiet with blogs and social media of late so I thought I’d provide a bit of an insight into what’s been going on with the Aikau UI framework.




On the whole things have been going exceptionally well. We've managed to maintain our weekly release cycle since the beginning of the year and have now made 18 releases (including 3 hotfix releases which were useful in proving that that element of our development process works).


Although the team is incredibly small (just the two of us at the moment), we’re now servicing 4 different Alfresco Engineering teams working on a variety of projects, along with a small handful of customer engagements.


Because we have such short Sprints we’re able to turn around requirements and bug fixes incredibly quickly, and thanks to our automated unit tests (which just passed the 75% code coverage mark with the 1.0.16 release) we’re able to ensure backwards compatibility.


The test page for a new MultipleSelectInput form control created for another Engineering team 


Automated Testing

At the moment we only have automated testing against Firefox and Chrome (on a local Vagrant VM) but have already successfully tested against a Selenium Grid that uses Internet Explorer and are looking to start incorporating this into testing in the future. At the moment we still rely on manual testing to pick up IE bugs.


The teams that we’re supporting raise bugs and feature requests as they find them and we prioritize them as necessary, ensuring that bugs are prioritized above anything else to try to maintain zero technical debt.


Recent Code Coverage Results


Educational Material

As well as improving our unit test coverage we’re also trying to improve our JSDoc documentation and when we work on any module we look to try and provide a useful description and examples of how it should be used. We’re still a long way from where we want to be, but we are making steady progress.


Another way in which we’re trying to provide educational material for Aikau is with the new index page for the test application. If you were to clone the GitHub repository and run:

mvn clean install jetty:run


...then you could access the page at “http://localhost:8089/aikau/page/tp/ws/Index” and use the “Filter results” box to search for widgets or services that you might be interested in. We’re updating the unit test WebScript descriptor files to set more meaningful “shortname” and “description” values - once again, this is an ongoing process.


Unit Test Index Page 


Document Library

Although our primary goal is to support the other Engineering teams development work we have an ongoing background task in porting the Document Library over to use Aikau. When we initially started looking at this back in the very early days we were only trying to port the existing capabilities and find ways to harness the existing action handling code. Now we’re looking to improve the Document Library with features such as inline commenting; inline content creation and metadata editing; popup previews; and drag-and-drop version update. We also want to make sure that it’s possible to easily create a configurable Document Library within a Share page and a standalone Aikau client via library files that can be imported into your Aikau page WebScripts.


The Document Library isn't in bad shape at the moment - the biggest challenge now is to work through the remaining actions that aren't supported and find the best way of being able to support legacy Share based XML configuration for actions, as well as making it easy to use actions in non-Share based standalone clients. You can follow the progress we make by cloning this GitHub repository which is a simple Aikau client with a page showing the authenticated user’s “User Home” directory. It would be really good to get some feedback on what we’re doing - particularly with regards to whether or not you’d be able to customize this Document Library more easily to fit your specific use cases.




Pull Requests, Feature Requests and Bug Reports

The only less positive to report so far is the lack of pull requests that we've received. The Alfresco Community were apparently clamouring for an easier way of contributing code to Alfresco and Aikau provides the easiest way to do that so far. It’s possible that this is because it’s still very new and that only the recent 5.0.1 and 5.0.d releases support the external Aikau libraries.


I do see that we get a lot of traffic on the GitHub site (around 50 unique visitors per day) and that the tutorials are getting a lot of hits. We've also had a couple of external issues raised which we've tried to turn around as quickly as possible.


A screenshot from one of the tutorials hosted on GitHub 


I also note that there is still some general concerns about Aikau in the Alfresco IRC channel. Maybe this is to be expected as Aikau still needs to prove it’s worth in the field - but I can say that the feedback within the company is incredibly positive and Aikau is definitely showing its value in accelerating the rate of UI development work internally. Hopefully once we've set out the ways in which Aikau can guarantee future-proof customizations from release-to-release of Share then the benefit will be seen outside of Alfresco as well. One thing I would say is that the discussions on IRC never materialise into issues on GitHub or JIRA - if you have something you want fixing or improving then let us know! We've already implemented feature requests and bug fixes that came from the forums and have added others to the backlog to work on in future sprints.


Long Term Thinking

We know that we’re not following the latest trends (interestingly I've noticed that the conversation about the best UI framework to use has shifted from Angular to React in recent months, no doubt it will have moved on to something else 12 months from now) but there’s no reason to think that Aikau won’t be around for the long haul - especially when you consider that the vast majority of Share is built on YUI2 which is approaching its 10th anniversary. Our black-box, widget-based, declarative approach to page creation is also holding strong with rewrites and updates to widgets being made without needing to make any changes to the pages that use them. We’ve also been able to migrate from Dojo 1.9.0 to 1.10.4 fairly seamlessly where our unit tests were able to quickly identify the few bugs that the upgrade introduced.



So in summary it feels as though we’re on the right track. Our processes are working, we’re making regular releases, code coverage is steadily increasing, JSDoc is improving and we’re adding more widgets and services every week. If you've not tried out Aikau then why not follow the tutorial and see how easy it is to quickly develop reliable, web-based clients for Alfresco.


Sample JSDoc Page 

Filter Blog

By date: By tag: