Tag: Migration

Upgrading from Alfresco SDK 3.0 to 4.0

Alfresco recently announced the beta release of SDK 4.0. The release is long-overdue. Developers had become frustrated that Alfresco published generally-available releases of the platform while seemingly ignoring the fact that there was no compatible SDK that could be used to customize and extend version 6.x of the platform. At DevCon this week, Alfresco said they recognize that was not handled as best as it could have been and pushed hard to get the new release out.

Version 4.0 of the SDK uses the same familiar structure that developers used in previous versions and continues to use Maven for dependency management and packaging. But there are some significant changes happening under-the-covers.

Prior releases of the SDK used an embedded version of Tomcat and an in-memory database to allow devs to launch and run Alfresco, along with their customizations, without having to separately download and install the platform. Adding in a tool that does hot Java class reloading such as JRebel or Hotswap Agent adds a greater productivity boost because changes to things like actions, behaviors, and web scripts can be run immediately, with no restart in most cases.

From a developer’s perspective, your “flow” doesn’t change–the SDK still bootstraps your project into a familiar structure and runs Alfresco with your changes, along with hot-swapping, if you want. The SDK no longer uses embedded Tomcat and H2. Instead, it relies on Docker and Docker Compose. When developers run an SDK project, images from Docker Hub (Community Edition) or Quay.io (Enterprise Edition) are downloaded, overlayed with the developer’s customizations, and launched.

If that sounds painful, relax, it’s not that bad. And the SDK 4.0 docs have everything you need to get productive quickly.

If you’re like me, though, you have many projects, open source and otherwise, that you must now upgrade so you can test them against 6.x. Doing it manually isn’t terrible but it is a bit mind-numbing and can be error-prone. Never fear, though; for help, read on!

Lots of projects to upgrade? DevCon hackers have you covered!

I had the pleasure of participating in the Hack-a-Thon at DevCon again this year, organized, as usual, by community icon, Axel Faust. I wasn’t sure what project I would work on when I woke up that morning, but when I saw there was a group of folks interested in working with SDK 4.0, I joined the team.

First, the group of eight fellow hackers started testing the SDK. For many it was their first time working with SDK 4.0. Windows, MacOS, and Linux were all represented and the group covered the various types of archetypes (all-in-one, repo-only, share-only). Every developer was successful bootstrapping a project and launching the Docker containers using the script that ships with the SDK.

JRebel has worked fine for me in SDK 4.0 for both Community Edition and Enterprise Edition, but no one in the group could get HotSwap Agent, the free alternative to JRebel, working. Filip promised to file a issue on Github, so hopefully it is easy to fix.

While the crew of testers were hammering away, I documented the steps needed to upgrade from 3.0 to 4.0 and filed a pull request to add that to the already-helpful SDK 4.0 documentation. Ole has already merged it. Thanks, Ole!

With the upgrade steps documented and the rest of the team familiar with the tool, we moved on to the next phase: Automating the upgrade. The result is a new Github project called alfresco-sdk-upgrader that you can leverage to upgrade your own SDK projects. It isn’t as full-featured as we wanted. For example, if you’ve customized your SDK pom files you’ll need to manually merge those changes. But I think it is still useful in its current state.

Here’s a video of the script in action:

You can see that I start out with a project based on SDK 3.0.1. The alfresco-sdk-upgrader script does everything needed to convert it from SDK 3.0.1 to 4.0. After it runs, the video shows the new project structure and then you can see that the run script fires up the Docker containers.

Mitch and Omar did a lot of work on the script. I don’t think any of us were planning on writing bash when we arrived that morning, but they happily rolled up their sleeves and knocked it out. We’d love it if you’d test it out on your projects and, if you feel so inclined, make it better by filing a pull request.

Even if you don’t want to use the script, you should give SDK 4.0 a try while it is still in beta so you can provide your feedback. And, if you’re curious about what other fun stuff got cranked out a the Hack-a-Thon, take a look here.

Photo Credit: Upgrade in Progress by Ged Carroll, CC-by-2.0