Installing CRX

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

To install 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:

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.

The CRX Quickstart window shows the startup time:

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

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.

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.

This chapter covers the technical issues of:

• Supported Platforms and Levels
  
• Platform Notes
• Installation Prerequisites

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.

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.

Unsupported Configurations

• 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.

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

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).

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

• 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.

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.

CRX works with the following client platforms:

• Mozilla Firefox 10 is a Extended Support Release. Learn more about this on mozilla.org

Windows Vista, Windows 7, Windows 8

Note: On Windows Vista, Service Pack 2 of Windows Vista is required to connect Adobe CRX using WebDAV.

To successfully connect with Windows Vista, Windows 7 and 8 to an Adobe CRX instance that is not secured with SSL, basic authentication over unsecured network must be enabled in Windows. This requires a change in the Windows Registry of the WebClient:

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.

To improve responsivness of the WebDav Client under Windows - see Microsoft Support KB 2445570

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.

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.

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.

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.

This section tells you how to install CRX 2.3 and how to upgrade from CRX 2.2 to CRX 2.3 with in an App Server (respective Servlet Container).

Installation

• WebSphere 7
• JBoss 5.1
• WebLogic 10.3.5
• Tomcat 6

Upgrade

• General Steps
• Additional Application Server dependent steps

CRX 2.3 comes as a single war file to deploy.

If deployed the following will happen by default:

• the instance (Repository, Felix OSGI environment, bundles etc.) is installed in ${user.dir}/crx-quickstart where ${user.dir} is the current working directory, this path to crx-quickstart is called  sling.home
  
• the context root is the war file name e.g : crx-2.3.0
  

You can change the default behaviour in the following way:

• sling.home: configure the sling.home parameter in the WEB-INF/web.xml file of the CRX 2.3.0 war file before deployment, see the explanation in the web.xml for details.
  
• context root: rename the CRX 2.3 war file or see the App Server documentation how to change the context root of a web application
  

Server Preparation

• Let Basic Auth Headers pass through:
  • One way to let CQ to authenticate a user is to disable the global administrative security of the WebSphere server, to do so: go to Security -> Global Security and uncheck the Enable administrative security checkbox, save and restart the server.
• Increase VM memory settings:
  • in the websphere admin console (/ibm/console) go to Servers -> Server Types -> WebSphere application servers
  • choose server1
  • in the configuration tab open the Java and Process Management tree and select Process definition
  • open Java Virtual Machine
  • set e.g Initial Heap Size to 512, Maximum heap size to 1792
  • save it and restart the server
• If you want to install CRX 2.3 using context root = / then you have first to change the context root of the existing Default web application

Deploy CRX 2.3 web application

• Download CRX 2.3 war file
• If you like, make your configurations In web.xml  (see above in the General Description)
  • Unpack WEB-INF/web.xml fill
  • uncomment sling.home initial parameter and set this path as you need
    
  • Repack web.xml file
• Deploy CRX 2.3  war file
  • Choose a context root, ( too in step 6 if selected detailed steps one can edit the run modes, so it seems possible to config that even during deployment, not tested however)
• Start CRX 2.3 web application

Prepare JBoss server

• Set Memory arguments in bin/run.conf.bat ( resp run.conf for unixes)
  • set "JAVA_OPTS=-Xms128M -Xmx1792M -XX:MaxPermSize=512M"

• Delete completely the <application-policy-name="other> section in server\default\conf\login.config.xml

Deploy CRX 2.3 web application

• Download CRX 2.3 web app
• if you like, adapt the configuration for sling.home in WEB-INF/web.xml
• Rename CRX 2.3 war file to e.g. crx if you like to have crx as context root

• if you want to deploy the CRX 2.3 web app under context root /:
  • Rename the CRX 2.3 web app to ROOT.war
  • Start JBoss
  • Stop existing ROOT.war webapp
  • Rename existing ROOT.war folder to something else

• Start JBoss
• Copy CRX 2.3 war file into server/default/deploy
• Wait until installation has finished, check ${sling.home}/logs/error.log of CRX 2.3
  
• If the installation has finished
  • Stop CRX 2.3 web application
  • in ${sling.home}/sling.properties file add the following property: sling.bootdelegation.org.apache.xerces=org.apache.xerces.* (Assure that there are no trailing whitespaces!)
  • Restart web application again

This uses a simple Server Layout with only an Admin Server.

WebLogic Server Preparation

• In ${myDomain}/config/config.xml add to the security-configuration section:
  • <enforce-valid-basic-auth-credentials>false</enforce-valid-basic-auth-credentials> see on http://xmlns.oracle.com/weblogic/domain/1.0/domain.xsd for the correct position (per default to position it at the end of the section is ok)

• Increase VM Memory settings:
  • open ${myDomain}/bin/setDomainEnv.cmd (resp .sh)search for WLS_MEM_ARGS, set e.g set WLS_MEM_ARGS_64BIT=-Xms256m -Xmx2048m
  • search for MEM_MAX_PERM_SIZE, set e.g MEM_MAX_PERM_SIZE_64BIT=-XX:MaxPermSize=512m
  • restart WebLogic Server
• Create in ${myDomain} a packages folder and inside a crx folder and in it a Plan folder

Deploy CRX 2.3 web application

• Download CRX 2.3 war file
• Put the CRX 2.3 war file into the ${myDomain}/packages/crx folder
• Make your configurations In WEB-INF/web.xml if needed (see above in the General Description)
  • Unpack WEB-INF/web.xml file
  • uncomment sling.home initial parameter and set this path as you need (see General Description)
  • Repack web.xml file

• Deploy CRX 2.3 war file as an Application, (for the other settings use the default settings)
• Check that the installation has finished as mentioned above in the General Description (e.g. tailing the error.log)
• After Installation has finished add the needed additional property to sling.properties file:
  • Stop CRX 2.3 web application in the WebLogic /console gui
  • Go to ${sling.home} folder and add to the sling.properties file: sling.bootdelegation.weblogic.xml=weblogic.xml.*(Assure there are no trailing whitespaces!)
  • Start web application again
• You can change the context root in the Configuration tab of the web application in the WebLogic /console

Install Hotfix cq-5.5.0-hotfix-41445

Additionally you need to install Hotfix cq-5.5.0-hotfix-41445:

1. Login to package share.
2. Search for cq-5.5.0-hotfix-41445.
   
3. Download the hotfix zip file to disk.
   
4. Create a new folder called install in your crx-quickstart folder (where sling.home is pointing to).
5. Put the hotfix zip file into this crx-quickstart/install folder.

Restart the CRX 2.3 web app.

The basic upgrade procedure is the same for all Application Servers. Some Application servers need additional steps which are explained after the description of the basic steps.

1. Create a backupo of your instance.
2. Stop both the crx-launchpad and crx-explorer web applications using the administration interface of the application server.
   
3. Uninstall the crx-launchpad web application.
4. Uninstall the crx-explorer web application.
5. Stop the application server.
6. Remove the crx-shared.jar and jcr-2.0.jar from the app server's lib folder.
7. Remove the crx-quickstart/launchpad/startup folder.
8. Remove the following properties from crx-quickstart/launchpad/sling.properties file:
   • sling.home
   • sling.installer.dir
   • org.osgi.framework.storage
   • felix.cm.dir
   • org.apache.sling.launcher.system.packages
   • org.osgi.framework.system.packages
   • osgi-core-packages
   • osgi-compendium-services
     
   • jre-*
9. Go to the folder crx-quickstart/launchpad/config/org/apache/sling/commons/log
10. In that folder, edit the LogManager.config file and all files in the LogManager subfolder by replacing
    org.apache.sling.commons.log.file="../logs/error.log"
    with
    org.apache.sling.commons.log.file="logs/error.log"
11. Start the application server.
12. If you have installed crx in a different folder than crx-quickstart then you need to set the path to it in the web.xml file in the sling.home property (see comment in web.xml for sling.home for details)
    
13. Deploy the  CRX 2.3 web application into the appliction server.
14. Perform additional steps required for your Application Server ( see below)

WebSphere 7

none

JBoss 5.1

After the installation has finished:

• Stop CQ 5.5 we application
• in ${sling.home}/sling.properties file add the following property: sling.bootdelegation.org.apache.xerces=org.apache.xerces.* (Assure that there are no trailing whitespaces!)
• Restart web application again

WebLogic 10.3.5

• After Installation has finished add the needed additional property to sling.properties file:
  • Stop CRX 2.3 web application in the WebLogic /console gui
  • Go to ${sling.home} folder and add to the sling.properties file: sling.bootdelegation.weblogic.xml=weblogic.xml.*(Assure there are no trailing whitespaces!)
  • Start web application again
• You can change the context root in the Configuration tab of the web application in the WebLogic /console

Additionally you need to install Hotfix cq-5.5.0-hotfix-41445:

1. Login to package share.
2. Search for cq-5.5.0-hotfix-41445.
   
3. Download the hotfix zip file to disk.
   
4. Create a new folder called install in your crx-quickstart folder (where sling.home is pointing to).
5. Put the hotfix zip file into this crx-quickstart/install folder.

Restart the CRX 2.3 web app.

Tomcat 6

none

Installation Check

To check if all is installed you can:

• tail the error.log file to see that all content is installed
• look in /system/console that all bundles are installed

if you find a line like th following in the error.log, the installation has finished:

*INFO* [Calculate File System Status] com.day.crx.persistence.tar.TarUtils File system status: created 200 files in 62 ms (3225 ops/sec)

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.

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.