Tag: Developer

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

Exploring Blockchain

I’ve been exploring blockchain technology lately. In this post I’ll share what I’ve learned so far. I should point out that my interest is squarely on how blockchain can be applied to solving business problems–I’m less interested in cryptocurrency.

Blockchain: A Brief Intro

A blockchain, as the name suggests, is a linked chain of blocks. Each block contains arbitrary data and a link to the previous block. Because these links are created using cryptographic hashes, blocks are hard to alter. The chain is continuously growing. Transactions run which add new blocks, and those transactions are validated by other servers before they are accepted into the chain.

So a blockchain is like a database, but instead of running on a central server controlled by a single entity, the blockchain is distributed across many servers, and, depending on which blockchain you are talking about, the blocks in the chain may be visible to the public.

The reason blockchain is often referred to in the context of cryptocurrency is because cryptocurrencies use a blockchain as a distributed ledger to track cryptocurrency trades. But that is only one of many possible use cases.

Wrapping up this brief intro, realize there is no single blockchain. You can run your own private blockchain internally. Or, you could set up a private blockchain between your company and your partners. Or, you could leverage one of the public blockchain networks. It really depends on exactly what you are trying to do.

For more on the origins of blockchain, see The Wired Guide to the Blockchain.

Use Cases

To identify problems that are good candidates for blockchain applications it helps to summarize the technology’s most noteworthy characteristics:

  • Data blocks are immutable. Once added to the chain they can never be changed. This will lend itself to problems where we need to retain the data for a long time or where we need to ensure that once created, the data does not change. Currency trades have already been mentioned, but you can easily come up with other examples such as health records, vehicle service records, government documents, or electronic votes.
  • Distributed/No single point of control. The distributed nature of the blockchain is attractive for multiple reasons. First, there is no single point of failure. If a server goes down or a company goes out of business, the chain is still intact and functional. Second, the data is automatically made available to every node in the network. This means you don’t have to solve data sync or replication–it just happens.
  • Transparency. In a public blockchain, every block is visible to everyone. Some of the data might be encrypted or hard to make sense of out-of-context, but you can inspect it, if you want.
  • Trustworthiness. I’ve already mentioned the difficulty in hacking the data. Another aspect of trustworthiness is about making sure that any logic that runs as part of the blockchain runs the same way every time. Yes, that logic could contain bugs, backdoors, or bad actors doing nefarious things, but the blockchain guarantees that it will always execute the same way every time.

Here’s a simple example that leverages all of these strengths. Suppose we decide to start a temperature prediction market in which participants try to predict the temperature in a given city on some date months into the future. We could store the prediction (predicted temperature, city, date, user) on the blockchain as well as the actual daily temperature readings.

We’re capturing data and that data is distributed across the network, which is cool, but we can also store logic on the blockchain–some implementations call these “smart contracts”, but they are really just scripts. In this example, when an actual temperature reading is saved the script will determine winners and losers by comparing the actual temp with the predictions.

If we wanted to add a reward mechanism to our prediction market, a prediction could have an associated wager amount. The smart contract would then not only be responsible for tracking the predictions that came true, but could also move funds from losers to winners, all without any middleman to make sure that happens.

This example takes advantage of the strengths of blockchain:

  • Once a prediction is made or an actual temperature reading is captured it cannot be changed (immutability).
  • If a server shuts down the actual readings can still be captured, predictions can be validated, and wagers can be paid (distributed).
  • If someone wants to make sure their prediction was captured correctly, they can inspect the block (transparency).
  • And, finally, no intermediary is needed to pay off the bet–the contract is guaranteed to be executed as written when the conditions that trigger it are met (trustworthiness).

A Developer’s Perspective

I wanted to experiment with some of these concepts on my own, so I started with Ethereum. Ethereum is an open source blockchain platform. You may have heard of people trading a cryptocurrency called Ether (ETH). You can use the same Ethereum platform to develop and run your own distributed applications (“dapps”) regardless of whether or not they are related to cryptocurrency.

Ethereum developers use a command line tool called geth to perform tasks with their Ethereum nodes and a tool called Solidity to compile JavaScript into smart contracts.

To try this out I spun up an Ubuntu server, installed geth and Solidity, then worked through the Greeter example. It’s not very exciting–Greeter is essentially a hello world example. But, it does help you understand what it takes to start up a local test network and to write and compile smart contracts.

One of the immediate learnings is that transactions on Ethereum cost money (called “gas”). Even if you are running a test network, you must first mine enough Ether on your test network before you can run a transaction. On the live network, the cost of running a transaction goes to the miners who are running servers that are busy validating transactions and updating the blockchain.

Another gotcha for me was that your miner has to keep working while you deploy your smart contract. It makes sense now–the smart contract is stored on the blockchain and therefore it must be validated like any other transaction, but it was definitely not clear to me while working through the tutorial.

Ethereum was definitely interesting, but I was looking for something a little more business-oriented. That’s when I found Hyperledger Fabric.

Hyperledger is an umbrella open source project that includes several blockchain related sub-projects. One of those is called Fabric, which, like Ethereum, is a blockchain implementation, but Fabric has some features that make it more attractive to businesses, such as a modular architecture and the ability to assign permissions to data and smart contracts.

Another very attractive sub-project is Hyperledger Composer. Composer is a set of tools that abstract away some of the nitty-gritty details related to creating and managing smart contracts (called “chaincode” in Hyperledger parlance).

The easiest way to try Fabric and Composer is the IBM Blockchain Platform Playground Tutorial (IBM Is a major contributor to the Hyperledger project). This is essentially a quick intro that you work through in your web browser.

The Playground Tutorial is worth it to get exposed to the concepts, but I wanted to run everything locally. You can do that easily with Docker. IBM’s Developer Tutorial walks you through setup and then takes you through a very simple “commodity trading” example. This tutorial is just a little deeper than the Playground, but at least you are running everything in containers running on your machine.

Finally, I came across J Steven Perry’s Hyperledger tutorial on developerWorks. This three part tutorial was awesome. You essentially build a “perishable goods business network” that models how contracts, shipments, and payments work with growers, shippers, and importers. By the time you are done, you’ve got GPS and temperature sensors sending data to the blockchain, chaincode that is looking at the contract and sensor data to determine how much stakeholders should get paid based on contract terms, and a RESTful API that you can call to make the whole thing work.

This tutorial really highlights how a Hyperledger solution can be used to share data between business partners in a distributed fashion while ensuring that only relevant operations and data are exposed depending on stakeholder role.

The developer-friendly tooling also flattened the learning curve significantly when compared to my out-of-the-box experience with Ethereum. I’m not saying one platform is inherently better than the other–it depends on what you are trying to do. I just felt much more productive with Hyperledger Fabric and Composer.

Tangential Topics

As I was exploring blockchain I went down a few interesting “bunny trails” here and there. Rather than go into details, I’ll just provide links in case any of it looks interesting:

Summary

I’m really glad I took the time to dig into blockchain. The hype is definitely at a fever pitch. They say blockchain engineers are in high demand right now. I suspect that one day we’ll all have blockchain in our toolbox, selecting it to be part of our solutions when it make sense, just like we do with any other technology.

Photo Credit: Chain, by Astro, CC-BY 2.0

7 mistakes developers make when customizing Alfresco Share

I’ve seen more than my–ahem–fair share of Alfresco Share over the last several months. Many clients feel that their needs are so close to what Share provides out-of-the-box, that they can save time and money by starting with Share as the basis for their custom content-centric application. Whether or not that’s a good idea is the subject of another post. This post assumes that, for whatever reason, you find yourself customizing Alfresco’s Share client and wondering what are some of the common pitfalls to avoid. Here’s seven. Feel free to add to the list.

1. Ignoring client-side JavaScript minification

Here is a massive understatement for you: Alfresco Share has a lot of client-side JavaScript files. Most, if not all, of these are minified, or compressed, to reduce the size of a given page and increase client-side performance. If you’ve ever looked at the FreeMarker source for one of Alfresco’s pages, you may have seen something like this:

<@script type="text/javascript" src="${page.url.context}/components/blog/blog-common.js">

It looks like an everyday JavaScript reference but what’s up with that “@script” tag? It’s a FreeMarker macro. It switches out the JavaScript source file for the minified version when debug is turned off and uses the original uncompressed source when debug is turned on, which makes stepping through the client-side JavaScript much more pleasant.

There are two things you need to be aware of here. First, if you find yourself tweaking Alfresco’s client-side JavaScript, you’ll need to remember to deploy both the expanded and minified version of the file. Otherwise, when people turn debug on and off, they’ll see different results. Second, when you create your own client-side JavaScript, you need to minify your own code for the same reason.

You could turn debug on and leave it on (bad idea) or you could use a “normal” script tag and point to the non-minified versions of your JavaScript, but it is really easy to add minification as a part of your build, so you might as well set that up early in the project and you won’t have to worry about it later.

There are several JavaScript compressors out there. Here’s a link to the YUI Compressor. You can drop the JAR into your project and then invoke it from Ant quite easily. Ask Google for some examples.

2. Assuming Alfresco and Share are on the same host

When you install Alfresco it deploys a web application in the “/alfresco” context–that’s your repository and the old Alfresco Explorer client–and a second web application in the “/share” context. Depending on what you’re doing you might deploy numerous additional web apps based on Share or Surf.

Regardless of how you choose to deploy, you need to remember that there is no guarantee your app and Alfresco will be on the same machine, app server, or port number. One of the beauties of the Surf architecture is that you can scale it out across multiple app servers and they can all talk to the same (or multiple) Alfresco repository servers. The underlying Surf framework on which Share is based has configuration and helper variables you can leverage to deal with this. You should not be hardcoding “localhost” or any other hostname in your Share code.

3. Incomplete theme customization

Alfresco Share 3.3 has user-selectable themes. As part of your customization effort you can define your own theme and then configure that to be the default. An easy way to create your own theme is to copy one of the out-of-the-box themes and then modify it to suit your needs. The keys to cloning a theme successfully are:

  1. Copy one of the themes other than “Default”
  2. Search and replace references to the old theme name in the new CSS files (login.css, presentation.css, and yui/assets/skin.css)
  3. In the previous step, don’t forget yui/assets/skin.css!

4. Duplicating, rather than extending, Alfresco web scripts

Suppose you want to change something in one of Alfresco’s web scripts. You may be tempted to change the out-of-the-box controller JavaScript or FreeMarker views, but don’t do it. A nice thing about the web script framework is that you can override even just a single file that is part of a web script by placing your version of the file with the same name in the same folder structure under web-extension. This also works on the repository tier, but instead of web-extension you use the “extension” directory.

For example, maybe I want to extend the document-actions config XML in Share with my own settings. I will NOT copy my version over the top of Alfresco’s. Instead, I’ll put my copy in a file named “document-actions.get.config.xml” under WEB-INF/classes/alfresco/web-extension/site-webscripts/org/alfresco/components/document-details. When Alfresco loads the web script, it will use my version of the config.

5. Not using the web-extension directory

While we’re on the topic, all of your custom Share config files go in web-extension under the Share web application. Don’t put them in $TOMCAT_HOME/shared/classes and don’t put them in the Share web app’s classes/alfresco directory. Use the web-extension directory to keep your stuff separate from Alfresco’s. I also recommend doing the same with your client-side files–create a directory called “extension” for your client-side JavaScript, images, CSS, and so-on.

6. Using the same Tomcat server as the Alfresco repository during development

This one isn’t going to cause you problems, but it sure will slow you down. Even if your production Share web app will run on the same Tomcat as the Alfresco WAR, do yourself a favor: While you’re coding, use two Tomcats. On port 8080, you’ll run Alfresco and out-of-the-box Share. On some other port you’ll run a second Tomcat server with your custom Share- or Surf-based web app. That way, when you need to restart your custom Share app, you don’t have to wait for the repository to start back up. You’ll cut way down on the time you spend waiting for Tomcat to restart which, over time, can speed up your development cycle tremendously.

7. Failing to test on Alfresco’s supported browsers

Have I mentioned how much client-side JavaScript there is in Share? Every time you touch Alfresco’s JavaScript or create your own, you’ll need to test it on the browsers your client intends to use. So there are two recommendations here: First, make sure you are testing across Alfresco’s supported browsers. Second, make sure your clients only expect to use Alfresco’s supported browsers. Failure to do both of these can lead to some missed expectations on both sides. The browsers Alfresco supports for 3.3 are on the supported stacks page on the Alfresco web site.

What am I missing? Add a comment with your Alfresco Share street smarts.