CQ Services Every Project Should Configure

If you’ve spent any serious amount of time as a cq developer or administrator, you are probably aware of the ability to configure OSGI services both via the web console or via runmode scoped configuration folders in the CRX repository. This post is an attempt to document (perhaps for myself more than for anyone else) the services that I configure for every single CQ project, and that I think every CQ project should configure to fit their needs.

One note before I start; This post makes several references to configurations applying only to local/dev/qa/production instances. This is accomplished via a custom runmode for the instance level, another thing that I do for every project I work on.


This one is pretty basic. Scanning the error log that comes out of the box will only get you so far, and you quickly find that custom logging is needed. I, at a minimum, always configure the following.

You can obviously add more log files if your project dictates it, but I use this as a minimum starting point. Also, you may also want to configure log writers for each of your log files, for example to roll the logs on a more frequent basis then the default settings.

HTML Library Manager

It’s OK to leave this one with the default settings for all author instances, but on your production and QA publish instances, you’ll want to be sure to turn client library minification & gzip on, as well as set the max age header to some reasonable value such as 86400 (1 day). You will also want to disable debug and timing for security reasons (see next section).

Note that when minifying client libraries, you’ll also want to be sure you clear the /var/clientlibs cache with every build on these publish instances. This can be handled via a simple curl script that runs as part of your CI build process (you do have CI builds, right?).

Debug Settings

As covered in the CQ Security Checklist, there are several services you will want to configure on all publish instances for security reasons. These are:

Mail Service

Want your workflows to send emails, or really to send any emails from CQ? You need to configure CQ to use your corporate SMTP server. Also, see this post for a good way to configure this to point to a gmail account, which is very handy for local testing.

Externalizer Service

The externalizer service provides an easy way of generating external links to CQ Pages and Assets, which can then be used outside of a standard link, such as in an email sent to an author or end user. It’s little more than a set of name-value pairs, with some code and wiring in the background to generate the correct links based on what you give it. There are 2 predefined mapping for “author” and “publish” but the configuration allows you to define arbitrary mappings as well.

This is a service which will have a configuration for each cq environment you have (local, dev, qa, production) since they will all have unique URLs. You also will need to define a mapping for each website you intend to host on your CQ instance.

Then, at a code level you would use as follows to generate external URLs:

private Externalizer ext;
ext.externalLink(resourceResolver, "site1", "/path/to/my/page") + ".html";

See also the javadocs for the externalizer service.

Sling Webconsole Security Provider

This configuration allows you to specify an array of users and groups which can log-in to the felix webconsole. By default, only the admin user can access this, but for what should be obvious reasons, you don’t want to share the admin login credentials with everyone who needs to get to the felix console. Instead, simply configure this service to allow a custom group to login, then just add your users who should have access to the console to this group.

Page Statistics Service

This service is used by stats.jsp, included in the head of the foundation page template to update the impressions count which is shown in the site admin interface on author. The default configuration goes to http://localhost:4502, which obviously doesn’t work.

Please note that you should seriously consider modifying your CQ basepage templates to not include stats.jsp on your publish instances (or just remove it all together, at which point this service configuration isn’t required). In almost all cases, analytics should be driven from a full featured analytics package such as Site Catalyst of Google Analytics, and this little bit of data provides little to no value.

Configuration Package

For examples of each of these configurations, please see the attached package, which can be installed into CQ to create examples of each of the configurations I’ve discussed above. You will need to modify almost all of these configurations to fit your project needs, but the package should serve as a reasonable starting point.