Overview / CRX 2.3 Documentation / Deploying / 

Installing CRX

This document contains detailed instructions on how to install CRX using the Quickstart jar file and includes information on the following:

What is Quickstart?

Unlike many other programs, you install CRX by using a "Quickstart" self-running jar file. When you double-click the jar file, everything you need is automatically installed. A CRX quickstart jar file includes a JCR-compliant repository and Apache Sling, which is a web framework for developing web applications on Java.

The first time you start the jar file, it creates an entire JCR-compliant repository in the background, which may take several minutes. After the first time, startup is much quicker as the repository has already been created.

Note

The naming convention used here for the CRX quickstart file is:
    crx-<version>-<edition>.jar.

The name of the edition would for example be enterprise for the CRX enterprise edition. The version numbers might also include a datestamp.

Be sure to substitute the version and name of your edition of CRX wherever appropriate.

Installing, Starting, and Stopping CRX

This section describes how to install, start, and stop CRX instances. For troubleshooting tips during installation, see Troubleshooting.

Installing CRX

To install CRX:

  1. Copy the CRX quickstart jar file (crx-<version>-<edition>.jar) to the desired directory on the host file system.

    Caution

    Only US-ASCII characters are allowed in the name of the folder used to store the Quickstart jar (or any other runnable jar).

  2. Copy a valid license.properties file into the same directory as the quickstart jar file.

    Note

    Note: If when starting the application, you do not provide the license.properties file, CRX asks you for a valid license key. You can request a valid license key from Day at this time.

  3. Start CRX Quickstart for the first time.

    • When CRX is started for the first time, it will automatically create a crx-quickstart folder in the same directory as the quickstart jar file. 
    • Inside the crx-quickstart directory, CRX will place its working files and create a fresh repository.

    Due to this initialization process, the first startup will take longer than subsequent startups. See Starting CRX for detailed instructions on how to start CRX Quickstart.

Starting CRX

In order to start CRX, simply double-click CRX Quickstart or start CRX from the command line or a custom script.

To start CRX:

  1. Navigate to the quickstart jar file (crx-<version>-<edition>.jar), either in your GUI file-system window or in a terminal, using the command line.

  2. Do one of the following:

    • If using a GUI (for example, Windows Explorer or MAC Finder), double-click the quickstart jar file (crx-<version>-<edition>.jar).
    • If using the command line, enter the java command using the following principle:
      with a 32bit VM:
          java -Xmx384M -jar crx-<version>-<edition>.jar
      or, with a 64bit VM
          java -XX:MaxPermSize=128m -Xmx512M -jar crx-<version>-<edition>.jar
      CRX is ready when the message "Press CTRL-C to shutdown the Quickstart server..." is seen.

    Note

    By default, CRX will automatically open a browser window on startup. When starting CRX from the command line on a remote server, you may want to suppress this by adding the -nobrowser option to the above command line.

  3. In order to automate the startup of CRX, you can use a startup script.

    When CRX is started the first time, it places example startup scripts in the crx-quickstart/server folder. The start and stop scripts are for UNIX, Linux and Macintosh, the server.bat script is for Windows.

Note

See Configuring JVM Settings for CRX if you need to change some of the advanced JVM settings for CRX (such as JVM memory size).

CRX starts and automatically opens the appropriate page in your web browser. Once started, you have access to CRX. See the CRX User Guide for details on using CRX.

file

Showing Startup Statistics

The CRX Quickstart window shows the startup time:

file

This also forms a link to startup statistics of the individual elements:

file

Stopping CRX

To stop CRX, do one of the following:

  • If you started CRX from the command line, press Ctrl+C to shut down the server.
  • If you started CRX with the start script, now use the stop script.
  • If you started CRX by double-clicking on the jar file, click on the On button in the Quickstart window. This will change to Off as the server shuts down.

Configuring JVM Settings for CRX

CRX is a Java application and runs within a Java Virtual Machine runtime environment (java process within your operating system). The default settings of the JVM are usually correct for the majority of CRX use cases, but sometimes you need to adjust them to match your specific use case or the application running on top of CRX. One of the settings that might require modification is the JVM memory size.

Depending on how CRX is started, the table below presents the ways of changing the JVM settings for CRX.

 

Startup method
 Default JVM Memory
 How to change JVM settings
Double-clicking the quickstart.jar

384MB heap for a 32bit VM.
512MB heap and 128MB PermGen for a 64bit VM.

(equivalent to using the -Xmx and -XX:MaxPermSize JVM options)

 You cannot change these settings when using double-click. Please use other startup methods.

Command line:

java -jar quickstart.jar

 64MB
(default JVM setting; needs to be increased)
 

Specify the required settings on the command line (before the -jar parameter).

For example, to adjust the default memory setting to 512MB and the PermGen space to 128MB, use the following command line:

java -Xmx512M -XX:MaxPermSize=128M -jar quickstart.jar

Recommended values are the ones used when double-clicking the jar file, see above.

See Java JDK Tools, java launcher tool documentation for your version of Java (e.g., for Java 1.5)


Note: the Quickstart -fork option overrides JVM settings with its own defaults. Not recommended if you need full control over JVM settings. If you do need to use it, you can specify the extra JVM parameters using the -forkargs option.

Startup scripts:

startup.bat (Win)

start/stop (Unix)

Defined by script variables:

JVM_MINHEAP / JVM_MAXHEAP

CQ_HEAP_MIN / CQ_HEAP_MAX

 Change the settings in the startup scripts. Some settings (for example, memory) have dedicated script variables. You can also add arbitrary settings for JVM by adding options to the java launcher tool with the JVM_OPTS / CQ_JVM_OPTS script variables.

Technical Requirements

This chapter covers the technical issues of:

Supported Platforms

This document lists the supported client and server platforms for CRX. Day provides several levels of support, both for our recommended configurations and for other configurations. Please refer to the Installation Guide for detailed instructions and notes for installing and runninng CRX on the supported platforms.

Recommended Configurations

Day recommends these configurations and provides full support as part of the standard software maintenance agreement. The configuration is tested and known bugs are fixed. Issues that are submitted by customers in the form of a fully qualified request are addressed in future releases.

A: Supported Day provides full product support and maintenance for this configuration. This configuration is covered by Day's quality assurance process.

Note

Note: In previous releases, Day used three different support levels for the fully supported configurations (A,B,C). Currently the supported platforms are all on level A.

Configurations with Optional Support Agreement

Day expects these platforms to work. Support is available as an optional add on to the standard software maintenance agreement.

D: Validated, optional support available This configuration has been validated by Day or a third party, or it is or has been in productive use. This platform is only sporadically tested by Day or third parties. Day offers optional platform support service agreements for this configuration.
E: Expected to work The configuration is expected to work, and there are no reports to the contrary. Day offers optional platform support service agreements for this configuration.

Unsupported Configurations

Z: Not supported The configuration is not supported. Day does not make any statements about whether the configuration works and does not support it.

Server Operating Systems

CRX works with the following server platforms:

Platform Support Level 
Windows Server 2008 R2
 A: Supported
Windows Server 2008 A: Supported
Windows Server 2003 A: Supported
Solaris 10 A: Supported
Solaris 9 A: Supported
RedHat Linux Kernel 2.6 A: Supported
RedHat Linux Kernel 2.4 E: Expected to work
HP-UX 11i v1-3 A: Supported
IBM AIX 7.1 E: Expected to work
IBM AIX 6.1 A: Supported
SUSE Linux Enterprise Server 11 E: Expected to work
SUSE Linux Enterprise Server 10 D: Validated
Mac OS X Server
 D: Validated

  • Windows 2003 with SP2 is not able to connect to WebDAV. Please see Microsoft - Software Update for Web Folders (KB907306) for full details of the manual updates which need to be made.
  • Please note, that there is no differentiation on a minor version level if not stated explicitly.

Cloud Computing Environments

CRX works with virtual machines in the following cloud computing environments:

Amazon EC2
 Running non-clustered CRX

CRX running in virtual machines in the cloud computing environments is supported in compliance with Day's support policy for all other system components (operating system, JVM, application server, etc).

Java Virtual Machines

CRX operates with the following versions of the Java Virtual Machine (Runtime Environment).

Platform Support Level 
Oracle JRE 1.7.x Z: Not supported
Oracle JRE 1.6.x A: Supported
Oracle JRE 1.5.x D: Validated
Oracle JRE 1.4.2 Z: Not supported
IBM JRE 1.6 A: Supported
IBM JRE 1.5 D: Validated
HP JRE 1.5 E: Expected to work

  • The IBM JRE is only supported on IBM server platforms (AIX), or in conjunction with Websphere. For all non-IBM platforms, the Oracle JRE is supported.
  • The HP JRE is only supported on HP server platforms (HP-UX). For all non-HP platforms, the Oracle JRE is supported.

Servlet Engines / Application Servers

CRX runs on the following application servers.

You can run CRX without an application server, but you need a Servlet Engine. Both CRX, and therefore CQ5, ship with Adobe's CQSE servlet engine, which you can use freely and which is fully supported.

 Platform Support Level 
CQSE (as packaged with CRX Quickstart)
 A: Supported
Oracle WebLogic Server 10.3.5 (11g)
 A: Supported
BEA WebLogic Server 10.3
 E: Expected to work
IBM Websphere 8
 D: Validated
IBM Websphere 7
 A: Supported
IBM Websphere 6.1 D: Validated
Apache Tomcat 7
 D: Validated
Apache Tomcat 6
 D: Validated
JBoss Application Server 5 A: Supported
Jetty 7-8 E: Expected to work
Oracle / Open Source GlassFish E: Expected to work

Supported Client Platforms

CRX works with the following client platforms:

Note

Support for browsers with rapid release cycles:

Mozilla Firefox and Google Chrome release updates every few months. Adobe is committed to provide updates for CRX to maintain the support level as stated below with upcoming versions of these browsers.

Browser Support Level 
Microsoft Internet Explorer 9.0 A: Supported
Microsoft Internet Explorer 8.0 A: Supported
Microsoft Internet Explorer 7.0 A: Supported
Mozilla Firefox 12 A: Supported
Mozilla Firefox 10.0.x A: Supported
Mozilla Firefox 3.6.x E: Expected to work
Google Chrome 18 E: Expected to work
Apple Safari 5.1 E: Expected to work

Platform Notes

This section provides special notes and more detailed information about running CRX on certain platforms.

WebDAV Clients

Windows 2003

Windows 2003 with SP2 cannot connect to WebDAV. See Microsoft - Software Update for Web Folders (KB907306) for full details of the manual updates that need to be made.

Windows Vista

Windows Vista requires SP2 to connect to WebDAV.

To successfully connect with Vista SP2, basic authentication for webclients must be enabled. This requires a change in the windows registry to enable basic authentication on the client computer:

  1. Locate the registry subkey:
    • HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\WebClient\Parameters
  2. Add the BasicAuthLevel registry entry to this subkey using a value of 2 or more.

See Microsoft Support KB 841215.

IPv4 and IPv6

CRX can be installed in both IPv4 and IPv6 networks.

Operation is seamless as no special configuration is required, when needed you can simply specify an IP address using the format that is appropriate to your network type.

This means that when an IP address needs to be specified you can select (as required) from:

  • an IPv6 address
    for example http://[ab12::34c5:6d7:8e90:1234]:4502
  • an IPv4 address
    for example http://123.1.1.4:4502
  • a server name
    for example, http://www.yourserver.com:4502
  • the default case of localhost will be interpreted for both IPv4 and IPv6 network installations
    for example, http://localhost:4502

Installation Prerequisites

To install a CRX instance, you need the following:

  • Java Runtime Environment (JRE) version 1.6. See Supported Platforms for detailed requirements regarding the JRE.
  • 500 MB free disk space in the deployment directory.
  • 128 MB minimum memory
  • The CRX quickstart.jar file

The prerequisites above state the minimum, which is needed to start install or start a default repository. The actual resource requirements differ vastly depending on the configuration, applications running on top of the repository, or executed use cases.

Please note that you might need to start the installer with customized memory settings if you have very little free memory, as the default Quickstart memory settings are configured to allow for more flexibility in deploying bigger content applications on top of the repository.

Note

CRX Quickstart requires create and write privileges within the installation directory. Ensure that the user installing CRX has these privileges for the chosen directory.

CRX System Architecture

The CRX repository consists of two parts: 

  • A Web application that offers the JCR-compliant API and temporary data storage (in the form of the CRX session).
  • A persistent data storage, such as a database. By default, CRX uses the tar persistence manager.

Day recommends that you use the tar persistence manager, which is preferred. If you install the two parts on separate computers (for example if you use your central database server for persistent storage, or if you run Tar persistence manager on a networked storage device, like SAN or NAS), make sure that the CRX instance has excellent network access to the repository. Lags or elongated response times in the communication between the CRX instance and the persistent storage may cause severe performance issues.

Database

If you use a database persistence manager to store the CRX data in an external database (that is, a database on a server that runs independently from CRX), you need to set up the database before installing CRX. By default, CRX uses the tar persistence manager. If you need to configure a database persistence manager, see Custom Installation.

Installing CRX on an Application Server

This section tells you how to install CRX with an application server. Consult the Supported Platforms section to see the specific support levels provided for the individual application servers.

The generic procedure details the actions common to (and referenced in) the installation procedures for:

After installation you can install further content packages if required.

Consult the appropriate application server documentation for more information on installing web applications.

Note

The naming convention used here for the CRX quickstart file is:
    crx-<version>-<edition>.jar.

For example, crx-2.1.0-enterprise.jar, where 2.1.0 would be the <version> and enterprise the name of the <edition>. The version might also include a datestamp.

Be sure to substitute the version and name of your edition of CRX wherever appropriate.

Generic Procedure for Installing CRX with an Application Server

This section provides generic information about installing CRX with an application server.

The procedure (with minor deviations) is used for all web servers and is referenced from the instructions provided for the individual web servers.

After having installed the application server, install CRX as follows:

  1. Unpack the quickstart jar file without starting the installation.

    To do this start the CRX Quickstart jar with the option -unpack by typing, for example:

    java -jar crx-<version>-<edition>.jar -unpack

    This creates a folder <crx-installation-dir>/crx-quickstart containing the files and folders used for installation.

    Note

    You must start CRX from the command line.

    If you open the jar file directly, you activate the Quickstart installation and start the server.

  2. Stop your web application server (if running).

  3. Copy the following two jar files:

    • <crx-install-dir>/crx-quickstart/server/lib/container/jcr-2.0.jar
    • <crx-install-dir>/crx-quickstart/server/lib/container/crx-shared.jar

    to the application server folder that holds the shared libraries (shared by all applications deployed to the server).

  4. Restart your web application server.

  5. Deploy the following web applications:

    • CRX webapp: crx-explorer_crx.war
      It is recommended to deploy it with the context path /crx
    • Launchpad webapp: crx-launchpad.war
      It is recommended to deploy with the context path /

    These can be found in <crx-installation-dir>/crx-quickstart/server/webapps

    Note

    JBoss v5 - see the workaround required.

    Note

    If you decided to deploy any of the applications with a non-recommended context path, you need to follow these additional configuration steps.

  6. Note

    Websphere - see the additional step of Configuring the default JDK.

  7. Start the two applications.

  8. Register your CRX license:

    1. Access your CRX installation:
          http://<server>:<port>/crx/index.jsp
    2. Enter the serial number.

  9. Follow the Generic Procedure for Installing Content Packages to install CRX's initial content package (using the CRX Package Manager to Upload then Install the package):

        <crx-install-dir>/crx-quickstart/repository/install/crx-initial-content-<version>.zip

    Without this package, the CRX Launchpad instance is not a fully functional sling instance as it misses application bundles, initial content, welcome page and other elements.

Generic Procedure for Installing Content Packages

After you have installed CRX, you should install the CRX initial content package first. That ensures that your CRX instance is fully functional (welcome page, example applications, support for CRX IDEs, etc). The content package is available in the following location:

  • <crx-install-dir>/crx-quickstart/repository/install/crx-initial-content-<version>.zip.

After that, you can install any additional content packages you may have; for example, your Sling application, project content, amongst others.

To install content packages follow the procedure below:

Note

Starting and stopping web applications is specific to your application server.

Please refer to the documentation of the individual application server.

  1. Stop the following web application in your application server:

    • /       (the CRX Launchpad application)

  2. Navigate to the Package Manager in CRX:

    • http://<server>:<port>/crx/packmgr/index.jsp

  3. Log in to the appropriate workspace (usually the default workspace, crx.default).

  4. Use the CRX Package Manager to Upload then Install the CRX package(s). Alternatively, you can use Package Share to access and download packages to your local instance, and then install them.

  5. Start the following web application in your application server:

    • /       (the CRX Launchpad application)

  6. Confirm the operation of CRX.

    Note

    If you experience any problems, please restart CRX to ensure that all bundles are correctly started.

Installing CRX with WebSphere v6.1

To install CRX with WebSphere v6.1 you:

  • install Websphere
  • install CRX
  • configure the default JDK

Installing CRX

After installing WebSphere install CRX according to the generic procedure.

Note

Before registering your CRX license perform the additional step of Configuring the default JDK according to the procedure.

Configuring the default JDK

WebSphere v6.1 uses JDK 1.5. By default, the SAMLv2 JSP JDK source level uses JDK 1.3. As the SAMLv2 sample configuration uses the JDK 1.5 syntax, running it with the default source level will not work.

Use the following steps to configure the source level as 1.5:

  1. Within the deployed crx-explorer_crx.war, edit ibm-web-ext.xmi and add the following configuration parameter to specify the JSP engine:

    <jspAttributes xmi:id="JSPAttribute_1225281520121" name="jdkSourceLevel" value="15"/>

    Note

    Note: The integer (n) referenced in JSPAttribute_<n> must be unique within the file.

  2. Repeat for crx-launchpad.war.

    Note

    The default configuration directory for the web module is:
    <WebSphere-installation-dir>/profiles/profilename/config/cells/cellname/applications /enterpriseappname/deployments/deployedname/webmodulename/

    If you have already checked the option Use Binary Configuration the files are extracted to the following directory, where they can be edited:

    <WebSphere-installation-dir>/profiles/profilename/installedApps/nodename/enterpriseappname/webmodulename/

    Where <WebSphere-installation-dir> is the root directory of the web application server installation.

Installing CRX with WebLogic v10.3

To install CRX with WebLogic 10.3 you:

  • install WebLogic
  • configure the server locale
  • enable Basic Authentication Headers (to allow user authentication in CRX)
  • install CRX

Note

CRX deployment on an Oracle WebLogic application server requires version 10.3.0 or version 10.3.3 or later. A CRX deployment in WebLogic versions 10.3.1 or 10.3.2 does not work.

Configuring the Server Locale

After installing WebLogic v10.3 (for use with CRX), you must set the server locale to en_US to avoid errors such as:

java.lang.IllegalArgumentException: Bad date header: 'We 16:34:28 GMT'

These can occur when, for example, requesting a resource such as /libs/widgets/0.gif.

To configure the server locale on Microsoft Windows:

  1. Open the Control Panel.

  2. Open Regional and Languages Options.

  3. In the Regional Options tab, for Standards and formats select English (United States).

To configure the server locale on Linux or Unix:

  1. Set the environment variable LANG to en_US.

Enable Basic Authentication Headers

To enable out-of-the-box authentication of users in CRX, authentication by the application server must be switched off:

  1. Open <WebLogic-installation-dir>/user_projects/domains/<myDomain>/config/config.xml.

  2. Locate the element <security-configuration>.

  3. Add the following child element to it:

    <enforce-valid-basic-auth-credentials>
    false 
</enforce-valid-basic-auth-credentials>

  4. If you had already started WebLogic then you will need to restart it.

Installing CRX

After installing WebLogic install CRX according to the generic procedure.

Installing CRX with Tomcat v6

To install CRX with Tomcat v6 you:

  • install Tomcat
  • configure Tomcat access accounts
  • install CRX

Configuring Tomcat access accounts

After installing Tomcat v6, you must configure the access accounts as Tomcat enables neither admin nor manager access at installation. This must be manually enabled:

  1. Navigate to the Tomcat configuration folder.

  2. Edit tomcat-users.xml to include access for admin and manager. The configuration should look similar to the following example:

    <?xml version='1.0' encoding='utf-8'?> 
<tomcat-users> 
    <role rolename="manager"/> 
    <role rolename="tomcat"/> 
    <role rolename="admin"/> 
    <role rolename="role1"/> 
    <user username="both" password="tomcat" roles="tomcat,role1"/> 
    <user username="tomcat" password="tomcat" roles="tomcat"/> 
    <user username="admin" password="admin" roles="admin,manager"/> 
    <user username="role1" password="tomcat" roles="role1"/> 
</tomcat-users>

Installing CRX

After installing Tomcat install CRX according to the generic procedure.

Installing CRX with JBoss v4 or v5

To install CRX with JBoss v4 or v5 you:

  • install JBoss
  • install CRX
  • configure the JBoss Server Login Module

Installing CRX

After installing JBoss install CRX according to the generic procedure.

Note

When deploying the web applications in JBoss 5, there is a conflict between xml-apis and xercesImpl bundled with Jackrabbit and Jboss libraries.

Therefore, the following workaround is required:
1. Before deploying the CRX war it should be unpacked.
2. WEB-INF/lib/{xml-apis-1.3.x.jar,xercesImpl-2.8.x.jar} removed.
3. Then repacked and deployed as specified.

Configuring the JBoss Server Login Module

By default JBoss' default login configuration attempts to authenticate users against a list of users in the users.properties file. You must configure JBoss as follows to let login attempts by unknown users pass to the web application (CRX Explorer). The web application then processes authentication by itself.

  1. Open JBOSS_HOME/server/default/conf/login-config.xml for editing.

  2. In the section application-policy name="other" (at the bottom of the file) add the attribute unauthenticatedIdentity="nobody" to the login-module entry.

Additional Configuration Required when not using Default Contexts

Day recommends installing the product web applications under the default contexts (/ and /crx). If there are reasons why this is not possible (operations, deployment, etc), you can also deploy the web applications under other contexts.

You will need the following additional configuration step(s) if you do not use the default contexts (/ and /crx) for the webapps. The description below assumes that crx-launchpad.war is deployed into /launchpad, and crx-explorer_crx.war into /daycrx).

  1. The action to be taken depends on whether you will be using CRXDE or CRXDE Lite:

    • CRXDE Lite:
      Edit the configuration file WEB-INF/web.xml, of the CRX web application deployed to your application server. Configure the required launchpad context in the JCRExplorer servlet section:
    <init-param>
      <param-name>launchpad.ctx.path</param-name>
      <param-value>/launchpad</param-value>
      <description>Context path of the launchpad</description>
    </init-param>

    The location of the WEB-INF/web.xml configuration file is specific to the application server and its configuration, please consult the relevant third-party documentation.

    • CRXDE:
      Reconfigure the URL for the CRX server endpoint. See Changing the CRX Server Endpoint for instructions.
      You have to log in to CRXDE with the URL appropriate to your launchpad web application; for example, http://<server>:<port>/launchpad

Verifying the Installation

The following links can be used to verify that the installation is operational (all examples on the basis that the instance is running on port 8080 of the localhost, CRX is installed under /crx, and Launchpad under /):

  • http://localhost:8080/crx/
    The CRX administration Console.
  • http://localhost:8080/crx.html
    The CRX Welcome screen.
  • http://localhost:8080/crx/de/
    The CRXDE Lite console.
  • http://localhost:8080/system/console
    The Apache Felix Web Console.

Custom Installation

For any customization you want to make to the CRX installation, several options are available via the command line. You can either use the available options or rename the Quickstart file for custom uses.

Note

Available options and renaming conventions are described in the Quickstart help file, which is available through the –help option. To access in CRX, type java -jar crx-<version>-<edition>.jar –help.

Changing the Port Number by Renaming the File

The default port for CRX is 7402. If that port is not available or already in use, Quickstart automatically configures itself to the first available port number as follows: 7402, 8080, 8081, 8082, 8083, 8084, 8085, 8888, 9362, <random>. You can also set the port number.

To change the port number of a CRX quickstart file, you can rename the file by including a port number, for example, crx-quickstart-7503.jar. Renaming syntax is covered in detail in the quickstart help file (-help option).

Note

Note: You can also change the port number by adding the –port option.

Configuring a Persistence Manager other than Tar PM

To configure CRX to use a persistence manager other than the default Tar PM, you must modify the CRX war file before starting the installation.

To modify the persistence manager:

  1. From the command line, start Quickstart with the -unpack option: java -jar crx-2.0-enterprise.jar -unpack. Doing so unzips the distribution, where the default setup with TarPM is used for the crx.default workspace.
  2. Prepare the war file, so that you can edit it. See How to Edit Repository Settings - In the Configuration Files.
  3. Modify the configuration of the repository and workspaces using these instructions. Especially see Repository and Workspace setup, which describes how to change the persistence manager.

Note

Note: You can also change other advanced configuration options for your installation of CRX using this approach. See the Configuring section of Deploying CRX.

Changing Default Repository JNDI Name

When you change the JNDI repository name from the default virtual-crx to another name, make sure that the CRX Launchpad and other Apache Sling applications are also configured to use the new repository name. To configure a different repository name for Sling applications:

  • Go to CRX OSGi management console at http://localhost:7402/system/console/configMgr
  • Select the CRX client repository in the dropdown that lists configuration (if there are two, use the one that contains a long hexadecimal number), change the repository name parameter as required and save the configuration.
  • You might need to restart the CRX instance for the application to use the new repository.

Relocating or Preconfiguring the Repository

The default location of the folder holding the files of the CRX repository is:

crx-quickstart/repository/  

With the default configuration file being:

crx-quickstart/repository/repository.xml

Sometimes you may want to relocate, or preconfigure, the repository; for example, when installing without a cluster or when using a different Persistence Manager.

Relocation must be configured before installation:

  1. Create the new directory (<new-location>) for the repository files.

    For example:

        <crx-installation-dir>/repositoryRelocated/

  2. Navigate to the <crx-installation-dir> directory (holding the installation jar file crx-<version>-<edition>.jar and license.properties).

  3. Create a new file (in <crx-installation-dir>):

    With the following entries:

    repository.home=<new-location>

    This is used to relocate the repository. Files required for the repository will be created here upon installation.
    For example, repository.home=repositoryRelocated

    repository.config=<new-location>/repository.xml

    This specifies the location of repository.xml. This version can be edited with your customizations. The location does not have to be the same as above, but is often.
    For example, repository.config=repositoryRelocated/repository.xml

    For example:

    repository.home=repositoryRelocated
    repository.config=repositoryRelocated/repository.xml

  4. Extract the template configuration file.

    The installation jar file:

        cq-<version>-<edition>.jar

    contains a war file:

        ../etc/server/webapps/crx-explorer_crx.war

    that in turn holds a template configuration file:

        ../WEB-INF/repository-template.xml

    You need to extract this template configuration file from these two archive files.

  5. Copy the extracted configuration file:

        ../WEB-INF/repository-template.xml

    to:

       <new-location>/repository.xml

    For example, repositoryRelocated/repository.xml.

  6. Edit this new version of repository.xml.

    In the section <Module class="com.day.crx.vlt.AutoInstaller">, there is a definition for the directory parameter. Replace the reference to ${rep.home} with crx-quickstart/repository/install:

        <param name="directory" value="${rep.home}/install" />

    with

        <param name="directory" value="crx-quickstart/repository/install" />

    Note

    This install directory must be explicitly referenced as the initial content packages are automatically extracted to this location when the installation jar file unpacks. These packages must be installed for CRX to start.

    Note

    If required, you can make other changes in repository.xml to preconfigure the repository.

  7. Start the installation procedure; files needed for the repository will be saved in the new location; for this example they will be under:

    <crx-installation-dir>/repositoryRelocated/

    Note

    You will still have a directory crx-quickstart/repository, but this will only contain files that were needed for the installation.

If you just want to preconfigure the repository (without relocating it) you only have to:

  • extract repository.xml to the required location
  • update repository.xml as required
  • create bootstrap.properties and define repository.config

Again, before starting the actual installation.

Troubleshooting Installation Issues

The following section describes some installation issues and their solutions.

Double-clicking the Quickstart jar does not have any effect or opens the jar file with another program (for example, archive manager)

This usually indicates a problem with the way your operating system's desktop environment is configured to open files with extension .jar.

It might also indicate that you do not have Java installed, or that you are using an unsupported version of Java.

As jar files use the ubiquitous ZIP format, some of the archiving programs might automatically configure the desktop to open jar files as archive files.

To troubleshoot, try the following:

  • Double check that you have at least Java version 1.5 installed
  • Try a context menu (usually right-mouse click) on the CRX Quickstart, and select "Open With...." Check if Java or SunJava is listed, and try to run CRX with it. If you have multiple Java versions installed, select the supported one.

Note

If you succeed with this step, and your operating systems offers an option to always use the selected program to run the .jar files, select it. Double-clicking should work from now on.

  • Sometimes reinstalling the supported Java version helps restore the correct association.
  • You can always run CRX using the command line or start/stop scripts as described earlier in this document.

My application running on CRX throws out-of-memory errors

CRX itself has a very low memory footprint. If the application running within CRX has bigger memory requirements or requests memory-heavy operations (for example, large transactions), the JVM instance where CRX runs needs to be started with appropriate memory settings. Use Java command options to define memory settings of the JVM (for example, java -Xmx512m -jar crx*.jar to set heapsize to 512MB).

Note

Specify the memory setting option while starting CRX from the command line. The CRX start/stop scripts or custom scripts for managing CRX startup can also be modified to define the required memory settings.

The CRX Welcome screen does not display in the browser after double-clicking CRX Quickstart

In certain situations, the CRX Welcome screens does not automatically display even though the repository itself is successfully running. This might depend on operating system setup, browser configuration, or similar factors.

The usual symptom is that the CRX Quickstart window displays "CRX starting up, waiting for server startup...." If that message displays for a relatively long time, enter the CRX URL into the browser window manually, using the default 7402 port, or the port on which the instance is running:
http://localhost:7402/

Also, logs may reveal the reason for the browser not starting.

Sometimes, the CRX Quickstart window has the message "CRX running on http://localhost:port/" and the browser does not start automatically. In this case, click on the URL in the CRX Quickstart window (it is a hyperlink) or manually enter the URL in the browser.

If everything else fails, check the logs to find out what has happened.

Because CRX installs only into a directory, there is no need for an uninstall utility. Uninstalling is as simple as deleting the entire installation directory, although how you uninstall CRX depends on what you want to achieve and what persistent storage you use.

Note

Day highly recommends that you back up your repository before deleting CRX. If you delete the entire <crx-installation-directory>, you will delete the repository. To keep the repository data before deleting, move or copy the crx-quickstart/repository folder somewhere else before deleting the other folders.

If persistent storage is embedded in the installation directory, for example, in the default TarPM installation, deleting folders removes data as well.

If your installation of CRX uses external storage, for example, a database server, removing folder does not remove the data automatically, but it does remove the storage configuration, which makes restoring the JCR content difficult.

CRX starts, but the crx-quickstart folder is missing

In most cases, the crx-quickstart subfolder is created in the folder, where the quickstart .jar file is located. Quickstart creates this folder as a subfolder of the current working directory of the Java process running the CRX instance.

In some cases it's possible that the Java process is started in a different directory than the quickstart .jar file. It might happen, e.g., when the quickstart file is double clicked, and the operating system desktop is configured to open .jar files with Java somewhere else, e.g., in the home folder of the current user. In this case, the crx-quickstart will be located there.

This can be avoided by running CRX from the command line or from the startup scripts, or by reconfiguring the launching mechanizm for the .jar files in the operating system desktop settings.

Uninstalling CRX

Because CRX installs only into a directory, there is no need for an uninstall utility. Uninstalling is as simple as deleting the entire installation directory, although how you uninstall CRX depends on what you want to achieve and what persistent storage you use.

Note

Day highly recommends that you back up your repository before deleting CRX. If you delete the entire <crx-installation-directory>, you will delete the repository. To keep the repository data before deleting, move or copy the crx-quickstart/repository folder somewhere else before deleting the other folders.

If persistent storage is embedded in the installation directory, for example, in the default TarPM installation, deleting folders removes data as well.

If your installation of CRX uses external storage, for example, a database server, removing folder does not remove the data automatically, but it does remove the storage configuration, which makes restoring the JCR content difficult.

Your comments are welcome.
Did you notice a way we could improve the documentation on this page? Is something unclear or insufficiently explained? Please leave your comments below and we will make the appropriate changes. Comments that have been addressed, by improving the documentation accordingly, will then be removed.

COMMENTS

  • By Rachael Hawkins - 9:26 PM on Dec 10, 2010   Reply
    I'm looking for some addtional details on CQSE 4. Particularly:
    * what frameworks/standards has it been built upon
    * does Day recommend it over 3rd party tools (particularly Tomcat)
    * pros/cons of CQSE over 3rd party tools (again, Tomcat)
    Thanks!
    • By Greg Klebus - 10:24 AM on Jan 05, 2011   Reply
      CQSE is a servlet engine built by Adobe/Day to support the out-of-the-box deployments of CQ & CRX. It basically implements servlet specification (version 2.4 as of CRX 2.1).

      We generally recommend to use CQSE (and the default installation) unless there is a good reason to choose other application server (servlet container), e.g., company IT policy. The main advantage of CQSE is that it provides the best integration of out-of-the-box deployment features (installation, etc); it's also been chosen by the vast majority of our customers. Other supported application servers also work of course.

      Hope that helps.
    • By sam schalley - 7:04 PM on Feb 17, 2011   Reply
      Noticed there's a "-fork" input parameter for startup. At least the server outputs info regarding a -fork input parameter. Is it possible to set this parameter when using "java -jar" from the command line? I've tried several different times without any luck.
      • By phool chandra - 6:01 PM on Mar 11, 2011   Reply
        good startup..............
        • By rajc - 5:13 PM on Mar 17, 2011   Reply
          after installing the CRX 2.2 within TomCat 6. i am unable to create a new project.
          i am getting 404 not found error. "Please check that all necessary bundles are installed!"

          i have uploaded the initial and installed content packages.
          am i missing something?
          • By alvawb - 5:18 PM on Sep 08, 2011   Reply
            After what step are you getting stuck? Looking at the error logs may help. You may want to post the specifics of what you were doing to day-communique (at) googlegroups (dot) com.
            • By smixe - 2:36 PM on Apr 25, 2012   Reply
              i'm having the same issue ...
              • By alvawb - 2:53 PM on Apr 30, 2012   Reply
                Please post details of what you're trying to troubleshoot (including any error logs) to our dedicated CQ5 user forum at http://forums.adobe.com/community/digital_marketing_suite/cq5.
          • By Igor - 3:31 PM on Dec 01, 2011   Reply
            Upon installation via Package Manager there is the option to specifiy to overwrite the ACL with those defined in the package - is this option also avialable via Auto Installer?
            <Module class="com.day.crx.vlt.AutoInstaller">
            ...
            </Module>?
            • By jkautzma - 8:09 AM on Dec 05, 2011   Reply
              No, this is currently not possible. The AC import options that are used are the one that are defined in the properties.xml in the package.
              • By Igor - 9:02 AM on Dec 07, 2011   Reply
                Currently implies some kind of "may be in a later release"? ;)

                But anyway: thanks for the reply!
            • By mv - 9:38 PM on Dec 12, 2011   Reply

              I tried to create a separate workspace to use MySql persistence manager. Following is my workspace.xmlfile
              <?xml version="1.0" encoding="UTF-8"?>
              <Workspace name="mysqlworkspace" simpleLocking="true">
              <!--
              virtual file system of the workspace:
              class: FQN of class implementing FileSystem interface
              -->
              <!--
              <FileSystem class="org.apache.jackrabbit.core.fs.local.LocalFileSystem">
              <param name="path" value="${wsp.home}"/>
              </FileSystem>
              -->
              <FileSystem class="com.day.crx.core.fs.db.DbFileSystem">
              <param name="driver" value="com.mysql.jdbc.Driver"/>
              <param name="url" value="jdbc:mysql://localhost:3306/crx"/>
              <param name="user" value="root"/>
              <param name="password" value="crx"/>
              <param name="schema" value="crx"/>
              <param name="schemaObjectPrefix" value="rep_"/>
              </FileSystem>
              <!--
              persistence manager of the workspace:
              class: FQN of class implementing PersistenceManager interface
              -->
              <!--<PersistenceManager class="com.day.crx.persistence.tar.TarPersistenceManager"/>-->
              <PersistenceManager class="org.apache.jackrabbit.core.persistence.pool.MySqlPersistenceManager">
              <param name="driver" value="com.mysql.jdbc.Driver"/>
              <param name="url" value="jdbc:mysql://localhost:3306/crx"/>
              <param name="user" value="root"/>
              <param name="password" value="crx"/>
              </PersistenceManager>

              <!--
              Search index and the file system it uses.
              -->
              <SearchIndex class="com.day.crx.query.lucene.LuceneHandler">
              <param name="path" value="${wsp.home}/index"/>
              <param name="resultFetchSize" value="50"/>
              </SearchIndex>

              <!--
              Workspace security configuration
              -->
              <WorkspaceSecurity>
              <AccessControlProvider class="org.apache.jackrabbit.core.security.authorization.acl.ACLProvider">
              <param name="omit-default-permission" value="true"/>
              </AccessControlProvider>
              </WorkspaceSecurity>

              <!--
              XML Import configuration of the workspace
              -->
              <Import>
              <ProtectedItemImporter class="org.apache.jackrabbit.core.xml.AccessControlImporter"/>
              <ProtectedItemImporter class="org.apache.jackrabbit.core.security.user.UserImporter">
              <param name="importBehavior" value="besteffort"/>
              </ProtectedItemImporter>
              </Import>
              </Workspace>

              ----------------------------------------------------------------------------------------------------------------
              I am getting following exception
              org.apache.jackrabbit.core.config.ConfigurationException: Configured bean implementation class com.day.crx.core.fs.db.DbFileSystem was not found.
              at org.apache.jackrabbit.core.config.BeanConfig.newInstance(BeanConfig.java:217)
              at org.apache.jackrabbit.core.config.RepositoryConfigurationParser$6.getFileSystem(RepositoryConfigurationParser.java:1056)
              at org.apache.jackrabbit.core.config.WorkspaceConfig.getFileSystem(WorkspaceConfig.java:184)

              ----------------------------------
              I am using CQ5.4.




              • By jkautzma - 11:22 AM on Dec 13, 2011   Reply
                Hi, to help you debug this issue, we suggest to post your details to the following mailing-list:
                day-communique (at) googlegroups (dot) com
              • By Sam - 1:34 AM on Apr 28, 2012   Reply
                Trying to install CRX 2.3 on tomcat
                java -jar crxxxx.jar -unpack is not creating war files. There is no server directory created in crx quick start
                • By alvawb - 2:51 PM on Apr 30, 2012   Reply
                  Please post your problem and any associated logs to our dedicate user forum at http://forums.adobe.com/community/digital_marketing_suite/cq5.
                • By SAM - 1:37 AM on Apr 28, 2012   Reply
                  Is this 2.3 documentation or 2.2 documentation. Looks like 2.2 copied under 2.3 section with no modification.
                  • By Alexandre COLLIGNON - 10:28 AM on Apr 30, 2012   Reply
                    Hi Sam,
                    This is the CRX 2.3 documentation (as you can see in the breadcrum on the top of the page). The CRX 2.2 documentation can be found here http://dev.day.com/docs/en/crx/2-2.html. Even if the two documentations look similar now, modification can be done in the future so I encourage you to read the documentation related to your CRX version. Thank you for your feedback.

                    Alex

                  ADD A COMMENT

                   

                  In order to post a comment, you need to sign-in.

                  Note: Customers with DayCare user accounts need to create a new account for use on day.com.

                  ***
                  On this page:
                  - Installing, Starting, and Stopping CRX
                  - Installing CRX
                  - Starting CRX
                  - Showing Startup Statistics
                  - Stopping CRX
                  - Configuring JVM Settings for CRX
                  - Technical Requirements
                  - Supported Platforms
                  - Server Operating Systems
                  - Cloud Computing Environments
                  - Java Virtual Machines
                  - Servlet Engines / Application Servers
                  - Supported Client Platforms
                  - Platform Notes
                  - Installation Prerequisites
                  - CRX System Architecture
                  - Database
                  - Installing CRX on an Application Server
                  - Generic Procedure for Installing CRX with an Application Server
                  - Generic Procedure for Installing Content Packages
                  - Installing CRX with WebSphere v6.1
                  - Installing CRX with WebLogic v10.3
                  - Installing CRX with Tomcat v6
                  - Installing CRX with JBoss v4 or v5
                  - Additional Configuration Required when not using Default Contexts
                  - Verifying the Installation
                  - Custom Installation
                  - Changing the Port Number by Renaming the File
                  - Configuring a Persistence Manager other than Tar PM
                  - Changing Default Repository JNDI Name
                  - Relocating or Preconfiguring the Repository
                  - Troubleshooting Installation Issues
                  - Uninstalling CRX
                  Jump to Page Comments
                  Reviewed by TRUSTe: site privacy statement

                  Copyright © 2012 Adobe Systems Incorporated. All rights reserved.

                  Use of this website signifies your agreement to the Terms of Use and Online Privacy Policy.