You are reading the AEM 5.6 version of Installing AEM.
This documentation is also available for the following versions:
CQ 5.5 CQ 5.4 CQ 5.3
Adobe Experience Manager (AEM) is a server-side application that runs on the Java platform. It is available in two forms:
A standalone executable jar file referred to as a quickstart file.
A war file to be deployed in a third-party application server.
AEM is accessed entirely through the web browser. No client-side software, other than a compatible browser, is required.
The quickstart jar file contains the full stack needed for AEM. This includes:
Apache Felix OSGi container within which all other components are run.
Integrated HTTP server (no separate application server needed).
Apache Sling web application framework (provides REST-based request resolution).
CRX content repository that stores all content (no separate database needed)
AEM application built on the above stack (provides all the content management functionality and more).
The war file version of AEM includes all of the same components, except that the HTTP service is delegated to the application server within which the war file is deployed.
This section includes information on the following:
AEM system architecture is described in detail in Exploring AEM, which explains the underlying concepts and technologies.
Persistence Managers and Databases
The default installation of AEM (in either jar or war form) includes a built in persistent storage layer in which all content is ultimately stored. In some cases users may choose to re-configure AEM to use an external third-party database for storage. Any such database must, of course, be installed separately from AEM.
How to Install CQ Author and Publish Instances using Quickstart
Generally, when you set up Adobe CQ, you need to set up an Author and a Publish instance - see Author and Publish Environments for further details on the two types of environment.
Only US-ASCII characters are allowed in the name of the folder used to store the Quickstart jar (or any other runnable jar).
Note
The first time you start the jar file (either by double-clicking on it or via the command line), it unpacks itself and installs the CQ application in a sub-directory within the same directory as itself. However, once CQ is installed, restarting the jar file does not reinstall the system. It simply starts up the application.
Installing an Author Instance
This procedure describes how to set up a default Author instance on port 4502 of the desired host.
To install an author instance:
On the host file system, create a directory and name it author.
Copy the cq5-<version>.jar file into author/.
Rename cq5-<version>.jar to cq5-author-p4502.jar.
If you need a different port this can be set in the filename.
Copy a valid license.properties file into author/ as well (the same directory as the cq5-author-p4502.jar file).
If you do not provide the license.properties file, CQ will redirect you to the Welcome screen when starting the application, where you can enter a valid license key. You will need to request a valid license key from Adobe if you do not yet have one.
Start CQ Quickstart using one of the following methods:
If using a GUI file-system explorer, double-click the cq5-author-p4502.jar file.
Use a custom script located in the crx quickstart folder, such as server.bat to start CQ.
The Start and Stop scripts are for UNIX, Linux, and Macintosh. The server.bat script is for Windows.
Note
You cannot use a custom script when you install the cq quickstart jar file (the first time it is started) unless you expand the file first. Use the -unpack option on the command line to unpack the contents before running the script as in java -jar cq5-author-p4502.jar -unpack.
When the installation is completed, you are automatically presented with a new web browser window opening http://localhost:4502/.
With the default settings, the syndication agent points toward the publish instance at http://localhost:4503/.
Installing a Publish Instance
To set up a publish instance on port 4503 of the desired host, you perform the same steps as in installing an author instance except that you create a directory named publish (instead of author) and you rename the quickstart.jar file as cq5-publish-p4503.jar. You can select any port number.
To install a publish instance:
On the host file system, create a directory and name it publish.
Copy the cq5-<version>.jar file into publish/.
Rename cq5-<version>.jar to cq5-publish-p4503.jar.
If you need a different port this can be set in the filename.
Copy a valid license.properties file into publish/ as well (the same directory as the cq5-publish-p4503.jar file).
If you do not provide the license.properties file, CQ will redirect you to the Welcome screen when starting the application, where you can enter a valid license key. You will need to request a valid license key from Adobe if you do not yet have one.
Start CQ Quickstart using one of the following methods:
If using a GUI file-system explorer, double-click the cq5-publish-p4503.jar file.
Use a custom script located in the crx quickstart folder, such as server.bat to start CQ.
The Start and Stop scripts are for UNIX, Linux, and Macintosh. The server.bat script is for Windows.
You cannot use a custom script when you install the cq quickstart jar file (the first time it is started) unless you expand the file first. Use the -unpack option on the command line to unpack the contents before running the script as in java -jar cq5-publish-p4503.jar -unpack.
When the installation is completed, you can browse your site (for example, http://localhost:4503/content/geometrixx/en/company.html
Installing a CQ Instance - Generic Procedure
This procedure is a generic, quickstart procedure for installing CQ; it installs an author instance using default settings and file names. It is often used when testing, or other scenarios when you need a quickly available instance.
Copy the cq5-<version>.jar file to the desired directory on the host file system.
Copy a valid license.properties file into the same directory as the cq5-<version>.jar file).
If you do not provide the license.properties file, CQ will redirect you to the Welcome screen when starting the application, where you can enter a valid license key. You will need to request a valid license key from Adobe if you do not yet have one.
Start CQ Quickstart using one of the following methods:
If using a GUI file-system explorer, double-click the cq5-<version>.jar file.
Use a custom script located in the crx quickstart folder, such as server.bat to start CQ.
The Start and Stop scripts are for UNIX, Linux, and Macintosh. The server.bat script is for Windows.
You cannot use a custom script when you install the cq quickstart jar file (the first time it is started) unless you expand the file first. Use the -unpack option on the command line to unpack the contents before running the script as in java -jar cq5-<version>.jar -unpack.
When the installation is completed, you are automatically presented with a new web browser window opening http://localhost:4502/.
CQ Quickstart selects the first available port from the following list:
4502,8080,8081,8082,8083,8084,8085,8888,9362,<random>
Starting AEM is similar to installing it, you can:
double-click the AEM quickstart file
or start AEM from the command line
or use a custom script
To start AEM, navigate to the location of your quickstart jar file and do one of the following:
If using a GUI file-system explorer, double-click the quickstart jar file; for example:
cq5-<version>.jar
If using the command line, type:
for a 32bit VM: java -Xmx384M -jar cq5-<version>.jar
or, with a 64bit VM: java -XX:MaxPermSize=128m -Xmx384M -jar cq5-<version>.jar
To use a customized script you need to expand the quickstart.jar file first. Use the -unpack option on the command line to unpack the contents before running the script.
Various log messages will be shown on the command line, the actual appearance will depend on the platform you are using.
AEM starts and automatically redirects your web browser to the appropriate page, usually the login page; for example:
http://localhost:4502/
Once logged in, you have access to AEM WCM. See the AEM WCM User Guide for details on using AEM WCM.
Starting AEM from the Command Line
The start script is available under the <cq-installation>/bin directory. Both Unix and Windows versions are provided. The script starts the instance installed in <cq-installation> directory.
Those two versions support a list of environement variables that could be used to start and tune the AEM instance.
Environment variable
Description
CQ_PORT
TCP port used for stop and status scripts
CQ_HOST
Host name
CQ_INTERFACE
Interface that this server should listen to
CQ_RUNMODE
Runmode(s) separated by comma
CQ_JARFILE
Name of the jarfile
CQ_USE_JAAS
Use of JAAS (if true)
CQ_JAAS_CONFIG
Path of the JAAS configuration
CQ_JVM_OPTS
Default JVM options
Windows platform start.bat script example
SET CQ_PORT=1234 & ./start.bat
Unix platform start script example
CQ_PORT=1234 ./start
Note
The start script launches the AEM Quickstart installed under the <cq-installation>/app folder.
Accessing CRXDE Lite and the Apache Felix Management Console
Once AEM WCM has been started, you can also access:
CRXDE Lite - used to access and manage the repository
Web Console - used to manage or configure the OSGi bundles (also known as the OSGi Console)
Accessing CRXDE Lite
To open CRXDE Lite you can select CRXDE Lite from the welcome screen or use your browser to navigate to
http://<host>:<port>/crx/de/index.jsp
For example: http://localhost:4502/crx/de/index.jsp
Accessing the Web Console
To access the Adobe CQ Web console you can select OSGi Console from the welcome screen or use your browser to navigate to
http://<host>:<port>/system/console
For example: http://localhost:4502/system/console
or for the Bundles page http://localhost:4502/system/console/bundles
If you started AEM from either a script or the command line, press Ctrl+C to shut down the server.
If you have used the start script on UNIX, you must use the stop script to stop AEM.
If you started AEM by double-clicking the jar file, click the On button on the startup window (the button then changes to Off) to shut down the server.
Stopping AEM from the Command Line
The stop script is available under the <cq-installation>/bin directory. Both Unix and Windows versions are provided. The script stops the running instance installed in <cq-installation> directory.
Unix platform stop script example
./stop
Windows platform stop.bat script example
./stop.bat
Custom Installation
For any customization you want to make to the AEM installation, several options are available via the command line. You can either use the available options or rename the Quickstart file for custom uses.
Changing the Port Number by Renaming the File
The default port for AEM is 4502. If that port is not available or already in use, Quickstart automatically configures itself to use the first available port number as follows: 4502, 8080, 8081, 8082, 8083, 8084, 8085, 8888, 9362, <random>.
You can also set the port number by renaming the quickstart jar file, so that the file name includes the port number; for example, cq5-publish-p4503.jar or cq5-author-p6754.jar.
There are various rules to be followed when renaming the quickstart jar file:
When you rename the file, it must start with cq; as in cq5-publish-p4503.jar.
It is recommended that you always prefix the port number with -p; as in cq5-publish-p4503.jar or cq5-author-p6754.jar.
Note
This is to ensure that you do not need to worry about fulfiling the rules used for extracting the port number:
the port number must be 4 or 5 digits
these digits must come after a dash
if there are any other digits in the filename, then the port number must be prefixed with -p
the "cq5" prefix at the beginning of the filename is ignored
You can also change the port number by using the -port option in the start command.
Relocating or Preconfiguring the Repository
The default location of the folder holding the files of the CRX repository within AEM 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:
Create the new directory (<new-location>) for the repository files.
For example:
<cq-installation-dir>/repositoryRelocated/
Navigate to the <cq-installation-dir> directory (holding the installation jar file cq5-<version>.jar and license.properties).
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
If you want to use the default repository.xml as a starting point for your custom configuration, either take it from a default installation or extract it from the unpacked distribution:
# mkdir tmp # cd tmp # jar xf ../app/cq-quickstart-5.6.0-standalone.jar resources/install/15/com.day.crx.sling.server-2.4.23.jar # jar xf resources/install/15/com.day.crx.sling.server-2.4.23.jar crx-core-2.4.23.jar # jar xf crx-core-2.4.23.jar com/day/crx/core/repository.xml
You can now copy com/day/crx/core/repository.xml to the place you wish and remove the tmp directory afterwards.
Start the installation procedure; files needed for the repository will be saved in the new location; for this example they will be under:
<cq-installation-dir>/repositoryRelocated/
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.
Removing the Geometrixx Sites
The Geometrixx sites (Geometrixx, Geometrixx Mobile, Geometrixx Outdoors and Geometrixx Outdoors Mobile) are provided as samples and references. They can be removed by uninstalling packages available in AEM.
To remove the Geometrixx and the Geometrixx Mobile sites:
In your browser, go to Package Manager.
Select the latest cq-geometrixx-pkg-x.y.z.zip package. The Filters field displays the paths that are part of the package and that will be removed.
In the package toolbar, in the More drop-down menu, select Uninstall.
In the dialog confirm the uninstall.
To remove the Geometrixx Outdoors, the Geometrixx Outdoors Mobile and the Geometrixx Media sites follow the same steps as before and use the latest cq-geometrixx-outdoors-pkg-x.y.z.zip package.
You have now an "empty" AEM instance without a demonstration site.
Configuring a Persistence Manager other than TarPM
To configure AEM to use a persistence manager other than the default TarPM, you must modify the CRX war file before starting installation. See Configuring a Persistence Manager other than TarPM in the CRX documentation for detailed instructions.
Installing and Starting AEM as a Windows Service
Note
Be sure to perform the following procedure while logged on as Administrator or start/run these steps using the Run As Administrator context-menu selection.
Being logged on as a user with administrator privileges is insufficient. If you are not logged on as Administrator when completing these steps you receive Access Denied errors.
To install and start AEM as a Windows service:
Open the crx-quickstart\opt\helpers\instsrv.bat file in a text editor.
If you are configuring a 64-bit Windows server, replace all instances of prunsrv with one of the following commands, according to your operating system:
prunsrv_amd64
prunsrv_ia64
This command invokes the appropriate script that starts the Windows service daemon in 64-bit Java instead of 32-bit Java.
To prevent the process from forking into more than one process, increase the maximum heap size and the PermGen JVM parameters. Locate the set jvm_options command and set the value as follows:
set jvm_options=-XX:MaxPermSize=256M;-Xmx1792m
Open Command Prompt, change the current directory to the crx-quickstart/opt/helpers folder of the AEM installation, and enter the following command to create the service:
instsrv.bat cq5
To verify that the service is created, open Services in the Administrative Tools control panel or type start services.msc in Command Prompt. The cq5 service appears in the list.
Start the service by doing one of the following:
In the Services control panel, click cq5 and click Start.
In the command line, type net start cq5.
Windows indicates that the service is running. AEM starts and the prunsrv executable appears in Task Manager. In your web browser, navigate to AEM, for example, http://localhost:4502 to start using AEM.
Note
The property values in the instsrv.bat file are used when creating the Windows service. If you edit the property values in instsrv.bat, you must uninstall and then reinstall the service.
To uninstall the service, either click Stop in the Services control panel or in the command line, navigate to the folder and type instsrv.bat -uninstall cq5. The service gets removed from the list in the Services control panel or from the list in the command line when you type net start.
Redefining the location of the temporary work directory
The default location of the temporary folder of the java machine is /tmp. AEM uses this folder too, for example when building packages.
If you want to change the location of the temporary folder (for example, if you need a directory with more free space) then define a <new-tmp-path> by adding the JVM parameter:
-Djava.io.tmpdir="/<new-tmp-path>"
to either:
the server startup command line
the CQ_JVM_OPTS environment parameter in the serverctl or start script
Further options available from the Quickstart file
Further options and renaming conventions are described in the Quickstart help file, which is available through the –help option. To access the help, type:
java -jar cq5-<version>.jar –help
Loading quickstart properties: default
Loading quickstart properties: instance
Setting properties from filename '/Users/Desktop/AEM/cq-quickstart-5.6.0.jar'
--------------------------------------------------------------------------------
Adobe Experience Manager Quickstart (build 20130129)
--------------------------------------------------------------------------------
Usage:
Use these options on the Quickstart command line.
--------------------------------------------------------------------------------
-help (--help,-h)
Show this help message
-quickstart.server.port (-p,-port) <port>
Set server port number
-contextpath (-c,-org.apache.felix.http.context_path) <contextpath>
Set context path
-debug <port>
Enable Java Debugging on port number; forces forking
-gui
Show GUI if running on a terminal
-nobrowser (-quickstart.nobrowser)
Do not open browser at startup
-unpack
Unpack installation files only, do not start the server (implies
-verbose)
-v (-verbose)
Do not redirect stdout/stderr to files and do not close stdin
-nofork
Do not fork the JVM, even if not running on a console
-fork
Force forking the JVM if running on a console, using recommended
default memory settings for the forked JVM.
-forkargs <args> [<args> ...]
Additional arguments for the forked JVM, defaults to '-Xmx1024m
-XX:MaxPermSize=256m '. Use -- to specify values starting with -,
example: '-forkargs -- -server'
-a (--interface) <interface>
Optional IP address (interface) to bind to
-pt <string>
Process type (main/fork) - do not use directly, used when forking a
process
-r <string> [<string> [<string> [<string> [<string> [<string> [<string> [<string> [<string> [<string>]]]]]]]]]
Runmode(s) - Use this to define the run mode(s)
-b <string>
Base folder - defines the path under which the quickstart work folder
is created
-low-mem-action <string>
Low memory action - what to do if memory is insufficient at startup
-use-control-port
Start a control port
-ll <level>
Define launchpad log level (1 = error...4 = debug)
--------------------------------------------------------------------------------
Quickstart filename options
--------------------------------------------------------------------------------
Usage:
Rename the jar file, including one of the patterns shown below, to set the
corresponding option. Command-line options have priority on these filename
patterns.
--------------------------------------------------------------------------------
-NNNN
Include -NNNN.jar or -pNNNN in the renamed jar filename to run on port
NNNN, for example: quickstart-8085.jar
-nobrowser
Include -nobrowser in the renamed jar filename to avoid opening the
browser at startup, example: quickstart-nobrowser-8085.jar
-publish
Include -publish in the renamed jar filename to run cq5 in "publish"
mode, example: cq5-publish-7502.jar
--------------------------------------------------------------------------------
The license.properties file
--------------------------------------------------------------------------------
The license.properties file stores licensing information, created from the
licensing form displayed on first startup and stored in the folder from where
Quickstart is run.
--------------------------------------------------------------------------------
Log files
--------------------------------------------------------------------------------
Once Quickstart has been unpacked and started, log files can be found under
./crx-quickstart/logs.
--------------------------------------------------------------------------------
Uploading Packages
If you need to install further (often customized) packages for your installation see Uploading Packages in the CRX documentation for detailed instructions.
Installing AEM with an Application Server
This section tells you how to install AEM with an application server. Consult the Supported Platforms section to see the specific support levels provided for the individual application servers.
The installation steps of the following Application Servers are described:
Consult the appropriate application server documentation for more information on installing web applications, server configurations and how to start and stop the server.
General Description
Default behaviour when installing AEM in an Application Server
AEM comes as a single war file to deploy.
If deployed the following will happen by default:
the run mode is author
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 : cq5-5.6.0
Configuration
You can change the default behaviour in the following way:
run mode : configure the sling.run.modes parameter in the WEB-INF/web.xml file of the AEM war file before deployment
sling.home: configure the sling.home parameter in the WEB-INF/web.xml file of the AEM war file before deployment
context root: rename the AEM war file
Publish installation
To get a publish instance deployed you need to set the run mode to publish:
Unpack the WEB-INF/web.xml from the AEM war file
Change sling.run.modes parameter to publish
Repack web.xml file into AEM war file
Deploy AEM war file
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)
2 Instances on the same Application Server
For demonstration purposes it can be appropriate to install author and publish instance in one application server. For that do the following:
Change sling.home variable and sling.run.modes variables of the publish instance.
Unpack WEB-INF/web.xml file from the AEM war file.
Change sling.home parameter to a different path, (absolute and relative paths are possible).
Change sling.run.modes to publish for the publish instance.
Repack the web.xml file.
Rename the war files, so they have different names: e.g. one rename to cq5author.war and the other to cq5publish.war.
Use higher memory settings, e.g. for default AEM instances use e.g.: -Xmx3072m -XX:MaxPermSize=768m.
Deploy the two web applications.
After Deployment stop the two web applications.
In both author and publish instances assure that in the sling.properties files the property felix.service.urlhandlers=false is set to false (default is that it is set to true).
One way to let AEM 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 AEM using context root = / then you have first to change the context root of the existing Default web application
Deploy AEM web application
Download AEM war file
Make your configurations In web.xml if needed (see above in the General Description)
Unpack WEB-INF/web.xml file
change sling.run.modes parameter to publish
uncomment sling.home initial parameter and set this path as you need
Repack web.xml file
Deploy AEM 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)
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 AEM web application
Download AEM web app
Adapt any configuration for sling.home and sling.run.modes in WEB-INF/web.xml
Rename AEM war file to e.g. cq5author if you like to have cq5author as context root
Put license.properties file beside the sling.home folder (i.e. if used the default value put it into jboss bin folder)
if you want to deploy he AEM web app under context root /:
Rename the AEM web app to ROOT.war
Start JBoss
Stop existing ROOT.war webapp
Rename existing ROOT.war folder to something else
Start JBoss
Copy cq5author.war file into server/default/deploy
Wait until installation has finished, check ${sling.home}/logs/error.log of AEM
If the installation has finished
Stop AEM 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!)
Set Memory arguments in your conf file(e.g. standalone.conf)
JAVA_OPTS="-Xms64m -Xmx1792m -XX:MaxPermSize=512m
if you use the deployment-scanner for to install the AEM web application it might be good to increase the deployment-timeout, for that set a deployment-tiimeout attribute in the xml file of your instance (e.g configuration/standalone.xml):
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 cq folder and in it a Plan folder
Deploy AEM web application
Download AEM war file
Put the AEM war file into the ${myDomain}/packages/cq folder
Make your configurations In WEB-INF/web.xml if needed (see above in the General Description)
Unpack WEB-INF/web.xml file
change sling.run.modes parameter to publish
uncomment sling.home initial parameter and set this path as you need (see General Description)
Repack web.xml file
Deploy AEM war file as an Application, (for the other settings use the default settings)
The installation can take time...
Check that the installation has finished as mentioned above in the General Description (e.g. tailing the error.log)
You can change the context root in the Configuration tab of the web application in the WebLogic /console
If you like to deploy AEM with context root "/" then you have to change context root of the existing ROOT webapp:
Stop and undeploy ROOT webapp
Rename ROOT.war folder in tomcat's webapps folder
Start webapp again
Deploy AEM web application
Download AEM war file
Make your configurations In web.xml if needed (see above in the General Description)
Unpack WEB-INF/web.xml file
change sling.run.modes parameter to publish
uncomment sling.home initial parameter and set this path as you need
Repack web.xml file
Rename AEM war file to ROOT.war if you like to deploy it as root webapp, rename it to e.g cq56author.war if you like to have cq56author as context root
copy it into tomcat's webapps folder
wait until AEM is installed
Tomcat 7
Prepare Tomcat Server
Increase VM memory settings:
In bin/catalina.bat (resp catalina.sh on unix) add the following setting:
set "JAVA_OPTS= -Xmx1792m -XX:MaxPermSize=512m"
Tomcat enables neither admin nor manager access at installation.
Therefore you have to manually edit tomcat-users.xml to allow access for these accounts:
Edit tomcat-users.xml to include access for admin and manager. The configuration should look similar to the following example:
If you like to deploy AEM with context root "/" then you have to change context root of the existing ROOT webapp:
Stop and undeploy ROOT webapp
Rename ROOT.war folder in tomcat's webapps folder
Start webapp again
If you install the AEM web application using the manager-gui then you need to increase the maximal size of an uploaded file, as the default only allows 50MB upload size. For that open the web.xml of the manager web applicaion, webapps/manager/WEB-INF/web.xml
and increase the max-file-size and max-request-size to at least 300MB, see the following multipart-config example of such a a web.xml file:
<multipart-config>
<!– 300MB max –>
<max-file-size>314572800</max-file-size>
<max-request-size>314572800</max-request-size>
<file-size-threshold>0</file-size-threshold>
</multipart-config>
Deploy AEM web application
Download AEM war file
Make your configurations In web.xml if needed (see above in the General Description)
Unpack WEB-INF/web.xml file
change sling.run.modes parameter to publish
uncomment sling.home initial parameter and set this path as you need
Repack web.xml file
Rename AEM war file to ROOT.war if you like to deploy it as root webapp, rename it to e.g cq56author.war if you like to have cq56author as context root
copy it into tomcat's webapps folder
wait until AEM is installed
Verifying the Installation
The following links can be used to verify that your installation is operational (all examples are on the basis that the instance is running on port 8080 of the localhost, that CRX is installed under /crx and Launchpad under /):
http://localhost:8080/crx/de
The CRXDE Lite console.
http://localhost:8080/system/console
The Web Console.
Actions after Installation
Although there are many possibilities to configure AEM WCM, certain actions should be taken, or at least reviewed immediately after installation:
Read the remaining points on Security Checklist for tasks required to ensure that your system remains secure.
Review the list of default users and groups which are installed with AEM WCM. Check whether you want to take action on any other accounts - see Security and User Administration for further details.
Troubleshooting
This section includes detailed information on logs available to help you troubleshoot and also includes information on some of the problems you might encounter when installing AEM WCM.
Auditing records and log files relating to AEM can be found at various locations. The following is provided to give you an overview of what you can find where.
Working with Logs
AEM WCM records detailed logs. After you unpack and start Quickstart, you can find logs in:
<cq-installation-dir>/crx-quickstart/logs/
<cq-installation-dir>/crx-quickstart/repository/
Log file rotation
Log file rotation refers to the process that limits the growth of file by creating new file periodically. In AEM, a log file called error.log will be rotated once a day according to the given rules:
The error.log file is renamed according to the pattern {original_filename}.yyyy-MM-dd. For example on July 2010 11th, the current log file is renamed error.log-2010-07-10, then a new error.og is created.
Previous log files are not deleted, so it is your responsibility to clean old log files periodically to limit the disk usage.
Note
If you upgrade your AEM installation, note that any existing log file that is no more used by AEM will remain on the disk. You can remove them without risk. All new log entries will be written in the new log files.
Finding the Log Files
Various log files are held on the file server where you installed AEM:
<cq-installation-dir>/crx-quickstart/logs
access.log
All access requests to AEM WCM and the repository are registered here.
audit.log
Moderation actions are registered here.
error.log
Error messages (of varying levels of severity) are registered here.
request.log
Each access request is registered here together with the response.
stderr.log
Holds error messages, again of varying levels of severity, generated during startup. By default the log level is set to Warning (WARN)
stdout.log
Holds logging messages indicating events during startup.
upgrade.log
Provides a log of all upgrade operations that runs from the com.day.compat.codeupgrade and com.adobe.cq.upgradesexecutor packages.
To activate the debug log level for a Logger, set the property org.apache.sling.commons.log.level to debug in the repository. For example, on /libs/sling/config/org.apache.sling.commons.log.LogManager to configure the global Apache Sling Logging.
Caution
Do not leave the log at the debug log level longer than necessary, as it generates a lot of log entries, thus consuming resources.
A line in the debug file usually starts with DEBUG, then provides the log level, the installer action and the log message. For example:
The action has failed, and the installer cannot proceed.
1
Error
The action has failed. The installation proceeds, but a part of AEM WCM was not installed correctly and will not work.
2
Warning
The action has succeeded but encountered problems. AEM WCM may or may not work correctly.
3
Information
The action has succeeded.
Create a Custom Log File
Note
When working with AEM there are several methods of managing the configuration settings for such services; see Configuring OSGi for more details and the recommended practices.
In certain circumstances you may want to create a custom log file with a different log level. You can do this in the repository by:
If not already existing, create a new configuration folder (sling:Folder) for your project /apps/<project-name>/config.
Name: org.apache.sling.commons.log.LogManager.factory.config-<identifier> (as this is a Logger)
Where <identifier> is replaced by free text that you (must) enter to identify the instance (you cannot omit this information). For example, org.apache.sling.commons.log.LogManager.factory.config-MINE
Type: sling:OsgiConfig
Note
Although not a technical requirement, it is advisable to make <identifier> unique.
Set the following properties on this node:
Name: org.apache.sling.commons.log.file
Type: String
Value: specify the Log File; for example, logs/myLogFile.log
Name: org.apache.sling.commons.log.names
Type: String[] (String + Multi)
Value: specify the OSGi services for which the Logger is to log messages; for example, all of the following:
org.apache.sling
org.apache.felix
com.day
Name: org.apache.sling.commons.log.level
Type: String
Value: specify the log level required (debug, info, warn or error); for example debug
Configure the other parameters as required:
Name: org.apache.sling.commons.log.pattern
Type: String
Value: specify the pattern of the log message as required; for example, {0,date,dd.MM.yyyy HH:mm:ss.SSS} *{4}* [{2}] {3} {5}
Note
org.apache.sling.commons.log.pattern supports up to six arguments.
{0} The timestamp of type java.util.Date
{1} the log marker
{2} the name of the current thread
{3} the name of the logger
{4} the log level
{5} the log message
If the log call includes a Throwable the stacktrace is appended to the message.
Warning
org.apache.sling.commons.log.names must have a value.
Note
Log writer paths are relative to the crx-quickstart location.
Name: org.apache.sling.commons.log.LogManager.factory.writer-<identifier> (as this is a Writer)
As with the Logger, <identifier> is replaced by free text that you (must) enter to identify the instance (you cannot omit this information). For example, org.apache.sling.commons.log.LogManager.factory.writer-MINE
Type: sling:OsgiConfig
Note
Although not a technical requirement, it is advisable to make <identifier> unique.
Set the following properties on this node:
Name: org.apache.sling.commons.log.file
Type: String
Value: specify the Log File so that it matches the file specified in the Logger;
for this example, ../logs/myLogFile.log.
Configure the other parameters as required:
Name: org.apache.sling.commons.log.file.number
Type: Long
Value: specify the number of log files you want kept; for example, 5
Name: org.apache.sling.commons.log.file.size
Type: String
Value: specify as required to control file rotation by size/date; for example, '.'yyyy-MM-dd
Note
org.apache.sling.commons.log.file.size controls the rotation of the log file by setting either:
a maximum file size
a time/date schedule
to indicate when a new file will be created (and the existing file renamed according to the name pattern).
A size limit can be specified with a number. If no size indicator is given, then this is taken as the number of bytes, or you can add one of the size indicators - KB, MB, or GB (case is ignored).
A time/date schedule can be specified as a java.util.SimpleDateFormat pattern. This defines the time period after which the file will be rotated; also the suffix appended to the rotated file (for identification).
The default is '.'yyyy-MM-dd (for daily log rotation).
So for example, at midnight of January 20th 2010 (or when the first log message after this occurs to be precise), ../logs/error.log will be renamed to ../logs/error.log.2010-01-20. Logging for the 21st of January will be output to (a new and empty) ../logs/error.log until it is rolled over at the next change of day.
'.'yyyy-MM
Rotation at the beginning of each month
'.'yyyy-ww
Rotation at the first day of each week (depends on the locale).
'.'yyyy-MM-dd
Rotation at midnight each day.
'.'yyyy-MM-dd-a
Rotation at midnight and midday of each day.
'.'yyyy-MM-dd-HH
Rotation at the top of every hour.
'.'yyyy-MM-dd-HH-mm
Rotation at the beginning of every minute.
Note: When specifying a time/date:
1. You should "escape" literal text within a pair of single quotes (' ');
this is to avoid certain characters being interpreted as pattern letters.
2. Only use characters allowed for a valid file name anywhere in the option.
Read your new log file with your chosen tool.
The log file created by this example will be ../crx-quickstart/logs/myLogFile.log.
The Felix Console also provides information about Sling Log Support at ../system/console/slinglog; for example http://localhost:4502/system/console/slinglog.
Finding the Audit Records
Audit records are held to provide a record of who did what and when. Different audit records are generated for both AEM WCM and OSGi events.
AEM WCM Audit records shown when Page Authoring
Open a page.
From the sidekick you can select the tab with the lock icon, then double-click on Audit Log...
A new window will open showing the list of audit records for the current page.
Click OK when you want to close the window.
AEM WCM Auditing records within the repository
Within the /var/audit folder, audit records are held according to the resource. You can drill down until you can see the individual records and the information they contain.
These entries hold the same information as shown when editing a page.
OSGi Audit records from the Web Console
OSGi events also generate audit records which can be seen from the Configuration Status tab -> Log Files tab in the Adobe CQ Web Console:
Using the Verbose Option for Troubleshooting
When you start AEM WCM, you can add the –v (verbose) option to the command line as in: java -jar cq-wcm-quickstart-<version>.jar -v.
The verbose option displays some of the Quickstart log output on the console, so it can be used for troubleshooting.
Common 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 may 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 may automatically configure the desktop to open jar files as archive files.
To troubleshoot, do the following:
Double check that you have at least Java version 1.5 installed.
Try a context menu (usually right-mouse click) on the AEM WCM Quickstart, and select "Open With...."
Check if Java or Sun Java is listed, and try to run AEM WCM with it. If you have multiple Java versions installed, select the supported one.
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
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).
Specify the memory setting option while starting AEM WCM from the command line. The AEM WCM start/stop scripts or custom scripts for managing AEM WCM startup can also be modified to define the required memory settings.
If you have already defined your heapsize to 512MB, you may want to analyze the memory issue further by creating a heap dump:
To automatically create a heap dump when running out of memory, use the following command:
This generates a heap dump file (java_...hprof) whenever the process runs out of memory. The process may continue to run after the heap dump was generated. Usually, one heap dump file is enough to analyze the problem.
The AEM Welcome screen does not display in the browser after double-clicking AEM Quickstart
In certain situations, the AEM WCM Welcome screens does not automatically display even though the repository itself is successfully running. This may depend on operating system setup, browser configuration, or similar factors.
The usual symptom is that the AEM WCM Quickstart window displays "AEM WCM starting up, waiting for server startup...." If that message displays for a relatively long time, enter the AEM WCM URL into the browser window manually, using the default 4502 port, or the port on which the instance is running: http://localhost:4502/.
Also, logs may reveal the reason for the browser not starting.
Sometimes, the AEM WCM Quickstart window has the message "AEM WCM running on http://localhost:port/" and the browser does not start automatically. In this case, click on the URL in the AEM WCM 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.
Troubleshooting Installations with an Application Server
Page Not Found returned when requesting a geometrixx-outdoor page
Applies to WebLogic 10.3.5 and JBoss 5.1
When a request to geometrixx-outdoors/en page returns a 404 (Page Not Foun) then you may recheck that you have set the additional sling property in the sling.properties file needed for these specific Application Servers.
See in the Deploy AEM web application steps for the details.
Response header size can be greater than 4Kb
502 errors can indicate that the web server cannot handle the size of the AEM HTTP response header. AEM can generate HTTP response headers that include include cookies of size greater than 4Kb. Ensure that your servlet container is configured so that the maximum response header size can exceed 4kb.
For example, for Tomcat 7.0, the maxHttpHeaderSize attribute of the HTTP Connector controls limitations on header size.
Uninstalling AEM
Because AEM installs into a single directory, there is no need for an uninstall utility. Uninstalling can be as simple as deleting the entire installation directory, although how you uninstall AEM depends on what you want to achieve and what persistent storage you use.
If persistent storage is embedded in the installation directory, for example, in the default TarPM installation, deleting folders removes data as well.
Note
Adobe highly recommends that you back up your repository before deleting AEM. If you delete the entire <cq-installation-directory>, you will delete the repository. To keep the repository data before deleting, move or copy the <cq-installation-directory>/crx-quickstart/repository folder somewhere else before deleting the other folders.
If your installation of AEM 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.
JSP files are not compiled on JBoss
If you install or update JSP files to Experience Manager on JBoss and the corresponding servlets are not compiled, ensure the JBoss JSP compiler is correclty configured. For information, see the JSP Compilation Issues in JBoss article.
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.
In CQ5.5, the deployment is as easy as renaming cq5-<version>.jar to cq5-author-p4502.jar. However, in CQ5.6, it is not that easy. I have to rename cq-quickstart-5.6.0.jar to cq5-publish-p4503.jar and double-click the jar. Then, it will generate a folder [crx-quickstart]. Then, I double click the cq5-publish-p4503.jar to start the program. It seems very different between 2 versions. Because of that, it causes the deployment issues. How can I synchronize source code from author to publish? Because I will only use author to develop.
Thanks so much for your feedback. The deployment hasn't changed from 5.5. to 5.6 and you should be able to replicate from author to publish as you did before. Hope that helps.
Author and Publish instances are installed as two window services in the same machine. However, It cannot start author and publish services at the same time. Only able to start either of them. Please advise.
By
Alexandre COLLIGNON - 1:17 PM on Mar 20, 2013
Reply
Hi Harry, I would recommend you post your problem and any associated logs to our dedicate user forum at http://forums.adobe.com/community/digital_marketing_suite/cq5. Hope that helps, Alex.
Do you have both quickstart files using the same port? I have Author and Publish (cq5.3) running on a single machine as separate services by using 4502 for author and 4503 for publish.
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.
However, in CQ5.6, it is not that easy.
I have to rename cq-quickstart-5.6.0.jar to cq5-publish-p4503.jar and double-click the jar. Then, it will generate a folder [crx-quickstart]. Then, I double click the cq5-publish-p4503.jar to start the program. It seems very different between 2 versions.
Because of that, it causes the deployment issues. How can I synchronize source code from author to publish?
Because I will only use author to develop.
However, It cannot start author and publish services at the same time.
Only able to start either of them. Please advise.
I would recommend you post your problem and any associated logs to our dedicate user forum at http://forums.adobe.com/community/digital_marketing_suite/cq5.
Hope that helps, Alex.
Do you have both quickstart files using the same port?
I have Author and Publish (cq5.3) running on a single machine as separate services by using 4502 for author and 4503 for publish.
Note: Customers with DayCare user accounts need to create a new account for use on day.com.