Posts tagged "CRX"

Editing the content directory in CRXDE

CRXDE is the eclipsed-based tool used to to develop within the CQ and CRX repository. By default, only a few directories within the repository are visible. The content directory is not one of them. A setting in the repository must be change before it can be seen.

Go to /etc/crxde/profiles/default. There is a property, crxde:paths. This property is a list of String. Add /content to that list and restart CRXDE.

Watched File System Folders in CQ/CRX

Greg Klebus suggested using WebDAV to mount repository directories on the file system. Doing this, he said, the end user has access to file system directories on which CQ can automatically run workflows.

A quick example of this is mounting the DAM directory as WebDAV. When content is added or changed within the DAM directory of CQ, a workflow process will run automatically.

These are the steps I go through for using WebDAV with Windows 7 to do that very thing.

I mount the CRX repository as a mapped drive within Windows 7 by right-clicking on the computer and selecting the Map Network Drive menu item. I pick the drive letter and, for my local installation, use the CRX WebDAV URL for my server [1].

Windows 7, out of the box, may not support WebDAV. To use WebDAV on a computer with Windows 7 you may need to install an update from Microsoft: Software Update for Web Folders [2]. You may want to see if it works without this update. It is an old software update and only lists Windows 2003 and Vista specifically. For instructions on how to get Windows 7 64bit, specifically, to work with WebDAV go to [3].

Within CQ 5.4, you can set the permissions of a directory under /var/dam to allow read/write or write privileges for the end user. When they drop an image into this folder there is a workflow that explodes the image, generates thumbnails, and creates the dam:asset for that image. The result of the process can be seen in the /content/dam directory. For CQ 5.5, images placed into /content/dam and its sub-directories will trigger the workflow.

[1] http://localhost:4502/crx/repository/crx.default



Place simple HTML and image files online with CRX and CQ

The Sling underpinnings of CRX and CQ allow for complex, conditional, rendering of content. That is fine and good, but what if you are just wanting to render a simple HTML page? CRX/CQ can serve static content as well. This includes any HTML files, images, SWFs and PDFs. This is a quick description of three ways to add this sort of content to your repository.

Using cURL

The most basic way to get static content into the CRX/CQ repository is to place it there using HTTP. Here is a simple example showing how to upload a page, sample.html, to a CRX server using curl:

curl -u admin:admin -T sample.html http://localhost:8080/content/sample.html

The resulting page is accessed at the same URL it was placed to.

Using WebDAV

By default, CRX/CQ allow WebDAV connections. With any WebDAV client, point to the CRX/CQ WebDAV endpoint at http://<host>:<port>/crx/repository/crx.default. I have a laptop with Windows 7 64 bit. WebDAV does not work with that operating system so I had to download a WebDAV client. My personal preference for a WebDAV client is CyberDuck (

Once you connect to your CRX/CQ instance you can place your static content within the repository.

Using Package Manager

The third way to add content to your repository is to create a package and import the package. The advantage of this method is that your content becomes a single file that is portable and able to archived. Packages can be created using tools such as Maven. The method I describe here uses no build tools.

First, create a folder node to contain your content within your repository using CRXDE Lite. Right click on the node you want to contain your new node and select the Create->Create folder… from the context menu.

This will bring up a dialog to name your new folder.

Once you have created and named your new folder, be sure to press the Save All… button within CRXDE Lite. Any changes are lost if you leave the page before saving.

At this stage go back to the main screen by pressing the CRXDE Lite logo at the top and the screen. On the main screen, select the Packages link to go to the Package Manager.

In the Package Manager you can create a new, empty, package for the folder you just created in your repository. Select the Create Package button.

This will open a dialog. Enter the name and version of your package. The group of the package should be the default, my_packages. Press OK.

The package is listed within the Package Manager. Right now this package is completely empty. Within the listing for the new package select the Edit… button.

Within the dialog that is opened, select the Filters tab and press the Add Filter button. Specify the root path of the package. Press the search button next to the root path field and select the folder within the repository for the Web pages. Press OK to select the folder and press the Save button in the Edit Package dialog.

In the listing for the new package press the Build button to the right of the Edit button. The Activity Log at the bottom of the page will show you the progress of the build. Once built, press the Download button in the package’s listing to save a copy to your computer.

This package file will be a zip file with content directories and manifest files. At this stage we finally get to your content. Place the content you want to include in your repository inside the package file. Place the content inside the directory of the zip file that matches the folder in the repository you wish to place it. Once the package file contains all of your content you can upload it to any CRX/CQ repository.

To upload the package, go once again to the Package Manager. Within the Package Manager is the Upload Package button.

A dialog to select a package file appears after the Upload Package button is pressed. Select your package file. Pressing OK adds the Package you selected to CRX/CQ. The package will be listed in the Package Manager. It very important to know that the package itself has not been applied to the repository. To apply the content changes found in the package file, press the Install button within that package’s listing.

Once the package is installed the content can be access through your CRX/CQ instance.

See Also

Apache Sling –  Discover Sling in 15 minutes has instructions on how to use the curl command to add and edit content within the Sling instance. This works the same way in CRX/CQ.

The documentation site for CRX/CQ,, contains documentation on WebDAV access to CRX/CQ and how to work with packages.



Installing CRX 2.1 or CQ 5.4 for Desktop Development

[Revised 11 April 2012: added section, Before You Begin]

CRX provides the base functionality for both CQ and Experience Services. CQ adds its own flavor of extended functionality to CRX and Experience Services does so as well. So they are all very similar and installing a development server on your local machine is the same for CQ, Experiences Services or generic CRX.

Before You Begin

To install CQ, Experience Services or CRX, you need the quickstart jar for the server and licensing as either a license key or the file. Quickstart files are cross platform. So the same quickstart will work on any compatible platform. You need to have both of these lined up ahead of time.

System Requirements

Adobe documentation describes the technical requirements for the servers at Your workstation should have 2 GB of free disk space and 1.5 GB of available memory. A Java run time, either version 1.5 or 1.6, is required. JRE 1.6 is preferred. JRE 1.7 will not work.

For development and testing on your local machine, the deployment requirements in the documentation can be more broad. The servers should work on computers with recent versions of the Windows and Macintosh systems.

Create a Deployment Directory, Rename Quick Start and Provide License

CQ, CRX and Experience Services all can be deployed using a single jar file, called a quickstart file, that is run by a Java JVM. This single jar contains everything needed to run, including the server, configuration files, and binaries. There are naming conventions for the quickstart files. Some of the conventions are mandatory, others override default behavior. If the quickstart is for CQ, the name of the quickstart file must start with cq-. If CRX, the name must begin with crx-. If Experience Services, the name must begin with adep-ria-. The port used by the server can be set using file naming, too. Place -[port] at the end of the file name (just before the .jar suffix) and the quickstart server will run on that port. The file name and the path to the quickstart file must not contain any spaces.

I have a directory, servers, at the root of my c drive to contain my server instances for testing and development. I place each quickstart file into its own directory. You do this because, when run, the quickstart will unpack itself within this directory. In my naming convention, I place the version of the server in the directory name.

These are examples of the quickstart files I use, where I place them and how I name them on the Windows 7 workstation.

Experience Services 10.0.0 using port 450



Experience Services 10.0.1 (service pack 1) using port 4503



CQ 5.5.0 using port 8081



Before the first time a quickstart is used, each of these directories should have two files inside of them. First, of course, is the quickstart jar itself. The second file that should be in each of these directories is a file. If the file is not present, the user will be prompted for a license key the first time the quickstart is run. If you do not have a file or license key, get in touch with either Adobe sales or Adobe customer support.

Start the Server the First Time

Using the command line, confirm the version of Java is correct. I have more than one version of Java installed for testing, so it is possible that the default Java is not correct even if you do have JRE 1.5 or JRE 1.6 installed.

java -version

If this does not return the correct version of Java, you will need to use the complete file path to Java when starting the server.

To start the server, change the directory of the command line to be the same directory that contains the quick start jar. Use Java to run the jar.

java -Xms1536m -jar cq-quickstart-5.5.0-20120220-8081.jar

The first time the server runs it creates a crx-quickstart folder in the same directory and unpacks its resources into this directory. It does some basic configuration based on the naming conventions used with the quick start file. Once the resources are unpacked, the quick start server runs.

Log Into the Administrative Console

Once the server has started, a browser window will open to allow you to log into administrative console of the server. The default user name is admin, the default password is admin.

You can start the server the same way from the command later. After the first time, starting it up will not take as much time. The jar is not unpacked.

For More Information

The developer site at,, contains more information about how to configure and use CQ, Experience Services and CRX.


Using the Data Store Garbage Collection in CRX and CQ

Andrew Khoury sent this information to me, basing the instructions on his solution to a customer’s problem.

I posted a solution to the problem in which the journal files for CRX grew and became a problem. The journal files are tar files in which the repository stores its information. However, items greater than 4KB are not stored in the repository tar files. Instead, CRX stores that data in a set of indexed files found within the crx-quickstart/repository/repository/datastore directory.

Like the tar journal files, these files have data appended, not rewritten. So the size of the datastore directory grows with each deployment that contains files larger than 4KB.

Just as there is a garbage collection functionality for repository tar files, there is a way to do garbage collection on the datastore. Running garbage collection removes unused items from the datastore directory and decreases the amount of its data.

Experience Services and CQ are both built using CRX as their base. So the instructions for CRX applies to the Experience Services and CQ servers, as well.

Running Datastore Garbage Collection

  1. Go to http://[server domain]:[server port]/crx and log in as administrative user
  2. Click Repository Configuration
  3. Click Datastore Garbage Collection
  4. Check all boxes and click Run (if it runs successfully then you are done)

If this process completes successfully, you are done.

If Datastore Garbage Collection fails with an error

Look at the error in the application server log and crx-quickstart/logs/crx/error.log. You may see “File not found: 123,” where 123 corresponds to the id number of a tar file. If so, first try to restore the tar file that corresponds to that id from a backup. For example, the tar file for id 123 would be crx-quickstart/workspaces/crx.default/data_00123.tar. The number in the data tar file name is always padded to five digits so add zeros before the number to make it five digits.

Next steps

If an error occurred, do the following. Do the rest of these steps even if you were not able to restore the missing tar file(s).

  1. Stop the application server or the quickstart server.
  2. If using *nix, log into the server via ssh and cd to the crx-quickstart directory. If using Windows, go to the crx-quickstart drectory.
  3. Make backups of the tar index files. Within the *nix environment use these commands:
    cd repository/version
    mkdir index_tar_backup
    mv index*.tar index_tar_backup/
    chmod 640 data*.tar
    cd ../workspaces/crx.default
    mkdir index_tar_backup
    mv index*.tar index_tar_backup/
    chmod 640 data*.tar
  4. Backup crx-quickstart/workspaces/crx.default/workspace.xml as crx-quickstart/workspaces/crx.default/workspace.xml.backup
  5.  Open crx-quickstart/workspaces/crx.default/workspace.xml in a text editor
  6. Comment out the PersistenceManagerelement:Before:
    <PersistenceManager class=""/>


    <!--PersistenceManager class=""/-->
  7. Add a new persistence manager element with the consistency check parameters set:
    <PersistenceManager class="">
    <param name="consistencyCheck" value="true" />
    <param name="consistencyFix" value="true" />
  8. Restart the application server or the quick start server
  9. Monitor start up by tailing crx-quickstart/logs/crx/error.log and watch fo any errors. In the error.log you will see something very similar to the following when the start up is complete:
     02.03.2012 15:39:52 *INFO * CRXHttpServlet: PackageShareServlet initialized. (, line 52)
     02.03.2012 15:39:52 *INFO * CRXHttpServlet: PackageManagerServlet initialized. (, line 52)
     02.03.2012 15:40:04 *INFO * TarUtils: File system status: created 200 files in 14 ms (14285 ops/sec) (, line 782)
    02.03.2012 15:40:04 *INFO * TarUtils: File system status calculated in 35 ms (, line 795)
  10. Go to http://[server domain]:[server port]/crx and log in as an administrative user
  11. Click Repository Configuration
  12. Click Datastore Garbage Collection
  13. Check all boxes and click Run
  14. Edit the file, crx-quickstart/workspaces/crx.default/workspace.xml, replacing it with the original version that was backed up.

503 error (service unavailable) while accessing services in CRX and CQ Quick Start

[Edited 9 July 2012 by Deke Smith: updated to no longer be specific to Experience Services]

One thing that causes this is using the wrong of Java with the server. CQ, CRX, and Experience Services requires at least version of the JDK (Java 6 update 26). But it will not work with version 1.7 JDK (Java 7). After installing Java, confirm the environment variable, JAVA_HOME, is set to the correct JDK directory.

It is easy to see what version of Java is on the server. Within a command prompt or terminal window type:

java -version

This command returns the version of Java on the machine.

What if you want to use the CRX Quick Start AND have Java 1.7 on your machine AND don’t want to set the JAVA_HOME variable to the Java 1.6 JDK? Within the server.bat file for the Quick Start is a setting in which the path to the Java SDK can be defined. The server.bat file is at [server directory]/crx-quickstart/server/server.bat. By default, it is set to JAVA_HOME:


It can be set to the path to another SDK:

set JAVA_HOME=c:\java\jdk1.6.0_26

For more information, see CQ Technical Requirements: Java Virtual Machines.

A quick way to find an out-of-control thread within CRX

It happens. A process is out of control, consuming system resources on your server and bringing performance to its knees. And many times it is very hard to tell what is behaving badly. For CRX on the Experience Services platform there is a rudimentary profiler that comes in handy when trying to troubleshoot this sort of problem.

The URL for the profiler is at http://[your crx host]:[your crx port]/crx/diagnostic/prof.jsp. This profiler is started, then stopped. It shows the number of times threads ran while the profiler was collecting, sorted in the order of frequency. That’s not a lot of information, but for a quick test to see what is wreaking havoc the built-in profiler works. For more complete profiling use a third party profiling tool such as YourKit.

Optimize the CRX repository

The CRX repository stores its data in tar files. Data is not overwritten or deleted as it is changed. The changed data is added to the tar files and older data continues to exist in the tar files, unused. Doing this makes the repository much more efficient. But this means that even small changes, if there are enough of them, will cause the amount of data residing in the jar files to become quite large.

How can the amount of space taken up by the repository’s tar files be quickly reduced?

CRX has functionality that works like memory garbage collection except for tar files. The tar files can be optimized with this functionality and reduced in size. When this happens the unused data stored in the tar files will be removed and the amount of data stored in the tar files can become much less.  By default, this optimization occurs in the early morning hours. If the size of the repository tar files becomes too large the optimization can be run manually any time it is needed.

Running the CRX respository tar file optimization

After logging into the Experience Services console with an administrator account select the link, Repository Management, on the right. This will take you to the management screen for the CRX repository. Select the link, Tar Persistence Manager Optimization.

On this screen is a field, Delay after optimizing one transaction. Changing this to be a higher number will cause the optimization to take longer while using less of the processor on the server.

To optimize the tar files of the repository, press the button, Start Optimization. While this is running you will see two buttons, Refresh and Stop Optimization. To get updates of the progress of the optimization you will need to press the Refresh button. When completed, a message is displayed: Optimization successfully finished.

For more information see:
Documentation for CRX Persistence Managers

Deconstructing Experience Services: the Java content repository

The Experience Services platform is built on top of a Java content repository (JCR). Day Software developed the JCR, CRX, that is in use by Adobe.

The term Java content repository can be used interchangebly for the Content Respository API for Java or for a software implementation of that API. The JCR is at heart an object database, with a hierarchical description of data. The API has standard methods to interact with an object database. It describes methods for importing and exporting data. It describes methods for searching the object database. Defined in the API, also, is data versioning.

Object databases (ODB) are interesting beasts. Most any type of data that is stored within a computer’s file system can be store in one. A Web site, with its whole directory and file structure, could be replicated in one. In addition, code can be stored and called inside an ODB. An ODB can be much more than the computer’s file system. Metadata can be defined for objects and the type of metadata stored can contain anything that the ODB can store.

My first introduction to an object database was with Userland Frontier back in the ’90s. The ODB contained scripts that ran a language called UserTalk. Website management capabilities were added to it and that is what I used it for. I learned the power of the practice of separating content from the code of the implementation. The information for the Website could be stored in the ODB not as HTML pages, but as content. The HTML was defined in separate templates, and the content and HTML code stayed distinct from one another until it came time to deploy. Then the pages would be created and placed online using FTP. A Web server was added to the ODB and Frontier became a content management system. Frontier had a lot of potential, but the company that developed it eventually stopped maintaining it.

The JCR at the core of Experience Services actualizes the potential that Frontier had, plus some. By itself, an object database does not do much. It is the parts that are hung from it that give it power.