SDK for Content Services 6 - Beta available!

[ohej]

It is an exciting time here at Alfresco. We are working on a lot of improvements to the product, especially the way developers integrate and extend our products. In this brave new world of containers, micro services, message queues, cloud connectors and REST APIs we are laying out the foundation of the developer experience of the future.

While the future looks more like what we call "out of process extensions", we recognise that it's a process that we are going through, and we do not have all the answers yet and there is still a need to make in-process extensions to the platform.

There are several ways to build extensions to Alfresco Content Services, but a popular approach has been using the "Alfresco SDK". Updates to the SDK to accommodate for the changes in ACS 6.X have been delayed - until now.

I'm happy to announce that we have released the first beta of the SDK, and we're hoping to get some feedback before the final release!

This beta release targets ACS 6.0 Community and Enterprise. We are actively working on support for 6.1, but this is not included in this first beta release.

The ACS SDK 4.0 brings some changes, so I wanted to write a blog post to give some details on some of the decisions and reasons behind.

Embracing containers and Docker

Previously the SDK relied on starting an embedded H2 database and using the Apache Tomcat Maven Plugin.

The first issue we hit was due to changes in the database layer of ACS. This meant that we cannot leverage H2 anymore and to work around this, an external database is required for running ACS.

The second issue we hit was the Tomcat plugin. Essentially it is stuck on Tomcat 7.X, which starts to give a lot of issues with Java 9 and 11. The plugin has not been updated in years, and while we could technically manage something to work for ACS 6.0 Community edition, some upstream dependencies in ACS 6.0 and 6.1 Enterprise impacted it. By leveraging Docker to spin up the repository we make a more future proof solution.

Alfresco Search Services is already an executable on its own, and since we provide containers for it already and we're embracing Docker in the SDK, it was a no-brainer to spin up search too. Same goes for Transform Services (Enterprise only).

By embracing this approach we have reduced a lot of the "magic" that happens inside the SDK. We have been able to remove hundreds of lines to deal with unpacking Solr, H2 DB Scripts and Tomcat configuration. This means the SDK is more maintainable moving forward.

Project structure

If you've previously used SDK 3.0 you should feel right at home. We provide roughly the same project structure, except instead of packaging the WAR file with modules applied to it, we now have a docker module that builds a custom Docker image for ACS with your module applied.

We still feature the same three archetypes: All-in-one, Platform JAR and Share JAR.

In addition, we had to put more logic into the run.sh / run.bat files, to accommodate for Docker.

Previously, you could use the Alfresco Maven Plugin to start the repository using "mvn install alfresco:run". In SDK 4.0 you will need to either manually start Docker Compose, or use the run utilities to do it for you. You can read more about it here.

Getting Started

We have a new getting started guide on GitHub. Please note this is still work in progress, feedback and contributions are welcome!

Here is the short version:
You need Java 8 or 11 along with Maven and Docker for Desktop.
- If you are on Windows 7 you will need the Docker Toolbox because Docker for Desktop is not supported for Windows 7. Docker Toolbox will work just fine.

Fire up a terminal and generate your project:

mvn archetype:generate -Dfilter=org.alfresco:‍‍‍‍

You can now select the archetype you wish, then make sure you select the version "4.0.0-beta-1":

Choose archetype:
1: remote -> org.alfresco.maven.archetype:activiti-jar-archetype (Sample project with full support for lifecycle and rapid development of Activiti JARs)
2: remote -> org.alfresco.maven.archetype:alfresco-allinone-archetype (Sample multi-module project for All-in-One development on the Alfresco platform. Includes modules for Platform/Repository JAR and Share JAR)
3: remote -> org.alfresco.maven.archetype:alfresco-amp-archetype (Sample project with full support for lifecycle and rapid development of Repository AMPs (Alfresco Module Packages))
4: remote -> org.alfresco.maven.archetype:alfresco-platform-jar-archetype (Sample project with full support for lifecycle and rapid development of Platform/Repository JARs and AMPs (Alfresco Module Packages))
5: remote -> org.alfresco.maven.archetype:alfresco-share-jar-archetype (Share project with full support for lifecycle and rapid development of JARs and AMPs (Alfresco Module
        Packages))
6: remote -> org.alfresco.maven.archetype:share-amp-archetype (Share project with full support for lifecycle and rapid development of AMPs (Alfresco Module
        Packages))
Choose a number or apply filter (format: [groupId:]artifactId, case sensitive contains): : 2
Choose org.alfresco.maven.archetype:alfresco-allinone-archetype version: 
1: 2.0.0-beta-1
2: 2.0.0-beta-2
3: 2.0.0-beta-3
4: 2.0.0-beta-4
5: 2.0.0
6: 2.1.0
7: 2.1.1
8: 2.2.0
9: 3.0.0
10: 3.0.1
11: 4.0.0-beta-1
12: 4.0.0-SNAPSHOT
Choose a number: 12: 11‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Fill out the groupId, artifactId and so on. Once your project is generated you can simply execute

./run.sh build_start‍‍‍‍

If you're on Windows simply use run.bat.

We have done tests on macOS, Linux, Windows 7 and Windows 10 and so far the results have been positive.

As mentioned above we are targeting ACS 6.0 for this first beta release.

We plan to release the final SDK 4.0 version around the same time as ACS 6.1, which of course means we will include full support for both 6.0 and 6.1 in the final release.

Stay tuned for more updates on this topic - we are iterating rapidly and hope the next beta will include support for ACS 6.1 as well as a number of enhancements, documentation and more. 

We welcome all kinds of feedback, feel free to open issues on GitHub or ask questions below.

For any contributions, please raise pull requests against the “sdk-4.0” branch on GitHub.

UPDATE Jan 28: Github links updated, some links were pointing to some feature branches which have now been merged.