Creating a Gold Copy of Adobe CQ – Part 5 of 5 – Optimization

There are some basic initial configurations we can set to get a better performance out of our CQ instances.  An average performance target value can be defined. Once this value is proven to be both achievable and maintainable, it can be used to monitor the performance of the website and indicate the development of potential problems.

  1. Optimize Tar Files: As data is never overwritten in a tar file, the disk usage increases even when only updating existing data. When optimizing, the TarPM copies data that is still used from old tar files into new tar files and deletes the old tar files that contain only old or redundant data. If there is only one file, optimization will have no effect. By default optimization is automatically run each night between 2 am and 5 am. and alternatively you can start optimizing the tar file manually.
  2. Merge Tar Index Files: If many entries are stored in the tar files, the number of index files may grow. The index files are automatically merged before and after the scheduled Tar PM optimization. To reduce the number of index files at other times, you can merge these index files manually through the JMX console.
  3. Consistency Checks: The Tar PM can check repository consistency and fix consistency problems at startup.
  4. Run Garbage Collector for Data Store: When a conventional WCM asset is removed, the reference to the underlying datastore record may be removed from the node hierarchy, but the datastore record itself remains.
  5. Check DataStore Consistency: CRX can check the consistency of the datastore to confirm that objects expected to be available in the datastore are actually there. Any datastore inconsistencies found will be logged.
  6. CRX search index’s resultFetchSize param: The SearchIndex element specifies the configuration of the search engine. By default the search index is managed by the text search engine Apache Lucene.
  7. TarJournal File Maximum size: Maximum size of a single journal file before it will get rotated. Default: 104857600 bytes (100 MB).
  8. Set logging level: By default logging level is set to INFORMATION. For performance purposes it can be switch to ERROR and set back to INFORMATION or DEBUG as required (logging levels: trace -> debug -> info -> warn -> error).
  9. Apache Sling JSP Script Handler: To improve performance you should disable as much as possible. In particular for production instances: disable Generate Debug Info, disable Keep Generated Java, disable Mapped Content, disable Display Source Fragments.
  10. Apache Sling Java Script Handler: Configure settings for the compilation of .java files as scripts (servlets). for production instances: Source VM and Target VM, define the JDK version as that used as the runtime JVM, disable Generate Debug Info.

This is the last part of our series of blogs discussion “Gold-Copy”. Remember to keep track to all configurations so you know what has been set, when it was set and who is accountable for it.

Every new developer should be given a copy of “Gold-Copy” and a set of instructions on how to install other tools such as JDK, Eclipse, Maven and Vault. Whenever you set new configurations you should share across all team members via CRX Packages. Should you restore a running production instance you can deploy your gold-copy and install CRX Packages for code and content.

“Maybe you can’t prevent Tragedy from happening but you can be prepare to recover soon enough suffering the less damage possible”.

Creating a Gold Copy of Adobe CQ – Part 4 of 5 – Security Configurations

For part 4 of this series we will discuss Adobe CQ Security Configurations. This group of configurations will help us ensure proper access to our repository (CRX). Demo users need to be removed, bulk access to the repository needs to be denied, developer’s console should be disabled and proper measures to protect against some other types of attacks need to be in place.

  1. remove Geometrixx users: besides removing Geometrixx Demo Websites you also need to remove default users for Geometrixx. For security purposes you might want to maintain only users that are specific for your application and those for administrative users.
  2. add clickjacking headers: To prevent clickjacking (when an attacker uses multiple transparent or opaque layers to trick a user into clicking on a button or link on another page when they were intending to click on the the top level page) we recommend that you configure your webserver to provide the X-FRAME-OPTIONS HTTP header set to SAMEORIGIN.
  3. disable WebDAV access: CRX and CQ come with WebDAV support that lets you display and edit the repository content. Setting up WebDAV gives you direct access to the content repository through your desktop. WebDAV should be disabled on the publish environment.
  4. disable CRXDE Light access: CRXDE Support should be disabled on a productive system before making it publicly accessible.
  5. disable Debug Mode: This is useful when developing as it allows the use of suffixes, but should be disabled on a production instance to ensure performance and security.
  6. protect against Cross-Site Scripting (XSS): Cross-site scripting (XSS) allows attackers to inject code into web pages viewed by other users. CQ applies the principle of filtering all user-supplied content upon output. Additionally, a web application firewall can be configured to add protection.
  7. prevent Denial of Service attacks (DoS): Limit the size of JSON representations responses, do not use number sizing for images.

The final set of configurations are for “optimizing” performance. Notice that not all “optimizing configurations” can be performed right after installing CQ; you will need to first gather some information on how your CQ instance is performing and then find specific measures to improve it.

Creating a Gold Copy of Adobe CQ – Part 3 of 5- Sanity Check Configurations

This group of configurations can be performed after installing Adobe CQ, just as we did with the  previous group (See Part 2: Custom Configurations.) This group of configurations is slightly different in that they can also be applied after having your instance running for some time. You will need different configurations for different environments (CI, QA, STAGING, PRODUCTION, etc) so run-modes will be used to set configurations for proper environment. Here are the steps that need to be completed for Sanity Check Configurations:

  1. Version Purge: in a standard installation AEM creates a new version of a page or node when you activate a page after updating the content. This default behavior can be customized to meet your requirements. These versions are never purged, so the repository size will grow over time and therefore need to be managed. You must limit the total number of versions AEM will remember.
  2. Custom Bundle’s logs: You can set AEM to create a separate log file for your custom bundles and jsp files; this will be really helpful for developers and system administrators as messages will be logged in different files and at different levels.
  3. CQ WCM page statistics/CQ multivariate statistics: Disable Page statistics and multivariate testing statistics for all environments in case you use other statistical tools.
  4. CRX Bundle cache Size: This caches bundles, consisting of a node with all its properties. This is used by all bundle-based Persistence Managers.  The default size of BundleCache is 8MB. If this is too small it can cause an excessive number of read-accesses to the underlying persistence layer.
  5. DAM renditions: By default AEM creates multiple thumbnails for images uploaded to DAM. Should authors not use such images then DAM renditions might be disable.
  6. CQ HTML Library Manager Settings: Configure this to control the handling of client libraries (css or js); including, for example, how the underlying structure is seen. For production instances (enable Minify, enable Gzip, disable Debug, disable Timing) and For JS development (disable Minify, enable Debug, enable Timing, enable Debug console).
  7. Email Service Configuration: configure servers and credentials for email notifications, mainly for email campaigns.

Up to know we’ve performed basic configurations to customize our instances. The next group is a most set of configurations to ensure proper access. Think of Adobe CQ’s CRX as a Data Base Management System (DBMS) you wish to protect access to.

Creating a Gold Copy of Adobe CQ – Part 2 of 5 – Custom Configurations

In the previous post on this series, Creating a Gold Copy of Adobe CQ Part 1 we mentioned the 4 major areas of configurations that System Administrators must deal with when recovering a crashed instance of Adobe CQ.

In this post, I will be covering the first of the four major areas, custom configurations. In this set of configuration we will review how to better integrate CQ into the underlying Java Virtual Machine (JVM) and Operating System, as well as configurations that need to integrate with other systems (like: dispatcher,  mappings and clustering).

Custom Configurations

You need to start with the crx-quickstart folder used in part 1 of this series. This folder will become our Gold Copy at the end of all 5 posts:

  1.  create Operating System user: create an specific operating system to perform all CQ related actions. These users should be consistent across all environments. a good name for these users could be cqauthor for all author instances and cqpublish for all publish instances ($ adduser cqauthor). If you are going to set the logs folder outside CQ’s installation folder (crx-quickstart) then you will also need to grant full access for these users to such linked folders ($ ln -s <targeted folder> logs)
  2. create destination folder: It is a good idea to make this folder consistent across all environments. A good CQ installation folder could be /opt/cq-author for author instances and /opt/cq-publish for publish instances
  3. test JDK: Always test the JDK installed in your system by executing > java -version;
  4. unpack CQ5.5: copy quickstart jar and license files into the targeted folder and rename jar file to cq-quickstart-p.jar ($ mv cq-quickstart<date>.jar cq-quickstart-p.jar). Don’t install CQ by executing the jar file ($ java -jar cq-<run mode>-<port number>.jar); if you do you will need to provide run mode and port number in the jar file name itself. Unpack ($ java -Xmx512m -jar cq-quickstart-p.jar -unpack)
  5. provide run-mode and port number: set CQ_PORT and CQ_RUNMODE according to the targeted environment
    CQ_RUNMODE=author,localhost. When setting port number make sure all servers have required ports opened. Also ti’s customary to use even numbers for author instances (4502, 4504, etc) and odds for publishers (4503, 4504, etc). For run-modes always provide the generic run-mode (author or publish) plus at least one specific such as QA, production and others. The more specific you get the more granular configurations you will be able to provide.
  6. set JVM options: provide default options and any custom you know are required
    -server: VM tuned for server applications; will start up slower but will run faster
    -Xmx: assigns the maximum size the heap can grow. Minimum possible value is 1024m. This value should be set to a 60% of the targeted OS available free memory ($ free -t -m)
    -XX:MaxpermSize: assigns the maximum size the “non-heap” or “perm area” can grow. Minimum possible values is 256M. This value should be set to a 25% of the targeted OS available free memory
    -Djava.awt.headless: Headless mode enables a JVM to perform Abstract Windowing Toolkit (AWT) operations on a machine that does not have a display, keyboard or mouse. Since most of the times you install/run CQ via a SSH connection then you must set this value to true Temporary directory used by JVM and java classes to create temporary files. If not set then default Operating System’s temp folder is used
  7. create start script for each and every instance and save a copy of such files
  8. install servicePack, hotfixes and feature packs: Policy dictates that for every new project with no already developed custom application (“starting from scratch”) you must install latest service pack and hotfixes available. As for the hotfixes most of the times they are privately available and you must request them through an Adobe care ticket. If you are creating a gold copy for an already running system then you have to options: 1) keep the Service Pack number and hotfixes already installed since the application is already running after all (not recommended) or 2) perform thorough tests of the application running with latest available Service Pack and hotfixes, if issues are found then the application must be updated
  9. Remove Geometrixx Web site: For lower environments such as CI, QA and others it’s okay to have these demo websites but not for production; such demo sites must be removed.
  10. Change admin user password: every new installation comes with an admin user set to the default password: admin. This password needs to be changed for security reasons.
  11. configure forward, reverse and flush agents: By default “admin” user is used to connect to other instances and perform replications between CQ instances and dispatcher. It’s a best practice to create a new user, specific for replication operations, and update all replication agents; also, deactivate agents that are not in use.
  12. mappings configuration: if multiple domains are going to be served by same CQ instances then CQ mappings need to be created and rewrite rules need to be added to Webservers.
  13. clustering: configure cluster nodes and make sure fail over and sticky connections are set
  14. dipatcher configuration: for those instances behind webservers a dispatcher need to be configured.

How To: Create a Gold Copy of Adobe CQ Instances – Part 1 of 5

A Gold Copy is an image of a fully patched and Custom Configured Adobe CQ instance that leverages the use of run-modes and sling:OsgiConfig nodes.  Once established, the Gold Copy can be “cloned” by System Administrators to efficiently create reliable subsequent installations.

Gold Copies, commonly used in the DBMS world, are still catching on in the world of CRX.  This is surprising when you consider how valuable they can be when something goes wrong, or in situations as routine as adding a new instance when a new developer joins the team.

run-modes [1] allow you to tune your AEM instance for a specific purpose such as: author, publish, test, development, intranet or others. By default, every Adobe CQ instance has to be one of two types: author or publish. These can be extended to address specific needs, for example: author,developer (author instance for developer’s local instances); author,qa (author instance for Quality Assurance instance); publish,preprod (publish instance in pre-production environment); or even much more specific settings like publish,production,us (production instance for publishing content in the US).

To start an instance in different run-modes, use one of the following methods:

  1. quickstart file name: you can provide author or publish run-modes only (depreciated)
  2. -r parameter: when running the java -jar… command you can add -r parameter to set the proper run-mode. For this you must rename your quickstart file to something like cq-quickstart-p4503.jar and provide -r option to the java command, ie: java -jar cq-quickstart-p4503.jar -r publish,qa -gui (publish instance for quality assurance)
  3. edit …/crx-quickstart/conf/
  4. edit start up script under bin folder (preferred method)

sling:OsgiConfig [2] nodes allow you to store configuration parameters for almost all bundles. This is the preferred method as opposed to manually accessing properties dialog box for each bundle in Adobe Web Console (Formerly known as Apache Felix Console).

Here are the steps to set configuration using OSGi config nodes in the repository:

  1. under /apps create a config sling:folder node for configuration affecting all instances (run-modes)
  2. under /apps create a sling:folder node for configurations affecting quality assurance publish instances
  3. under the newly created node create a new node for each OSGi PID you wish to configure; these node have to be of type sling:OsgiConfig
  4. add properties to the newly created nodes with the values you want to set such properties to

There are four major areas of configurations that System Administrators must deal with when installing Adobe CQ for the first time or when restoring a crashed instance. These areas are as important as having a healthy running instance. Blogs 2-5 will cover these sections, and they are: custom configurations, sanity configurations, security configurations and optimization.

Custom Configurations:

  •     Install Service Packs
  •     Remove Geometrixx Web site
  •     Modify Start Script
  •     Change admin password
  •     configure Forward Replication Agent
  •     configure Reverse Replication Agent
  •     configure flush Agent
  •     mappings configurations
  •     clustering author and publishers
  •     dispatcher configuration

Sanity Configurations:

  • version purge
  • Custom Bundles’ log
  • CQ WCM page statistics/CQ multivariate statistics
  • CRX Bundle cache Size
  • DAM renditions
  • CQ HTML Library Manager Settings
  • Email Service Configuration

Security Configurations:

  • remove Geometrixx users
  • change password to default users
  • create users for replication
  • add clickjacking headers
  • disable WebDAV access
  • disable CRXDE Light access
  • disable Debug Mode
  • protect against Cross-Site Scripting (XSS)
  • prevent Denial of Service attacks (DoS)


  • Optimize Tar Files
  • Merge Tar Index Files
  • Consistency Check and Fix
  • Run Garbage Collector
  • Check Datastore consistency
  • CSS and JS minify
  • CRX search index’s resultFetchSize param
  • TarJournal File Maximum size
  • Set logging level
  • Apache Sling JSP Script Handler
  • Apache Sling Java Script Handler
  • CQ HTML Library Manager Settings
  • Day CQ HTTP Header Authentication Handler

The crx-quickstart folder we will get after unpacking and applying all configurations described in all 5 parts of this blog (“Creating a Gold Copy of AEM/CQ instances“) will become our Gold-Copy.