Using curl to install CQ packages — and why it isn’t a good idea

CQ5 has a very good tradition of exposing APIs, which are accessibly by simple HTTP (in some cases even RESTful APIs). This allows one to access data and processes from external and is also a good starting point for automation.

Especially the Package Manager API  is well documented, so most steps to automate deployment steps really start here. A typical shell script to automate package installation might look like this:

FILENAME=`basename $ZIP`
CURL=curl -u admin:admin

$CURL -s -F package=@ZIP -F force=true $HOST?cmd=upload
if test $? -ne 0;
  echo “failed on upload"
$CURL -X POST -s $HOST/etc/packages/mypackages/$FILENAME?cmd=install
if test $? -ne 0;
  echo “failed on install"

As you see, it lacks any kind of sophisticated error handling. Introducing a good error handling is not convenient, as curl doesn’t return the HTTP status as a return code (but just if the request itself has been performed successfully), so you have a parse the complete output to decide if the server side returned a HTTP 200 or something else. Any non-seasoned shell-script-developer will probably just omit this part and hope for the best …

And even then: When your package installation throw an error during deserialization of a node (maybe you have a typo in one of your hand-crafted .content.xml files), the system still returns a http 200 code. Which of course it shouldn’t.
(The reason for the 200 is, that the code streams the installation progress on each node, and that the decision for the status code has to be done before all nodes are imported into the repository. Therefor the need for an internal status, which is one of the last lines of the result. Thanks Toby for this missing piece!)

And of course we still lack the checks if embedded bundles are starting up correctly …

So whenever you do such a light-weight deployment automation, be aware of the limits of it. Good error handling, especially if the errors are inlined in some output, was never a primary focus of shell scripting, and most of the automation scripts I’ve seen in the wild (and written myself, to be honest) never really cared about it.
But if you want to have it automated, it must be reliable. So you can focus on your other work, and not on checking deployment process logs for obvious and non-obvious errors.

On AEMHub I will talk about the importance of such tools and why developers should care about such operation topics. And I hope, that I can present the foundations of a small project aimed for proper CQ deployment automation.

2 thoughts on “Using curl to install CQ packages — and why it isn’t a good idea

  1. Hi,

    > curl doesn’t return the HTTP status as a return code

    Curl can actually return the http status code if configured properly. For example:

    curl –write-out %{http_code} –silent –output response.html ‘’

    However, as you have mentioned, CQ is not always returning a reasonable status code.

    1. Behrand,
      Thanks for your response. You show
      Yes, you can get the HTTP statusocde as single output written to stdout, but if you would like to have more information (like an error message contained in a response body) you need to deal again with grep and friends.

Comments are closed.