Set Up Run Modes in AEM

Run Modes in aem is used to tune up aem instance according to environment need. For example we want to have separate log levels at development,QA and production environment. Instead of going manually and changing them in felix console, we can create run modes which change log configurations automatically when we start the instance. Similarly we can also install separate bundles according to run modes.

Wondering what are run modes ? How to setup or create run modes in aem ? What are the advantages of using run modes? Then this tutorial is for you.

After completing this tutorials you will have a clear understanding about:-

Types of Run modes:

Run modes are basically categorized into two categories:-

  • Primary Run Mode(author,publish).
  • Secondary or Customized Run Mode(dev,qa).
Primary Run Modes:-

Primary run modes used at the time of installation and are fixed for the entire lifetime of that installation. There are two primary run modes provided from adobe author and publish.

Note:- We cannot change primary run mode after installation, as crx-quickstart folder is created after first installation according to run mode.

Secondary Run Modes:-

Secondary or Customized run modes are applied on each startup and can be changed with a restart of AEM instance. These are custom run modes defined for specific environment like development (, Testing( or production(

Run modes are identified by adding a suffix to folder name.

  • config -> applicable for all run modes
  • -> used in author run mode
  • config.publish -> used in publish run mode
  • config.<standard-run-mode>.<environment-specific-mode> -> used in the applicable run mode like dev,qa,prod etc.

Don’t worry we will see how to use them in details below.

Steps to Set up run modes:-

Follow below steps to set up primary or secondary run modes:-

Set up only primary run mode:-

If we don’t want secondary run modes, we can directly use primary run modes by renaming the aem jar file.

Naming convention for CQ 5.6 and earlier:-


Naming convention for AEM6 and Later:-

  • aem-<optional-version-or-indentifier>-<standard-run-mode>-<port-number>
  • aem- (For author environment)
  • aem- (For prod environment)

Note:- If there are any other digits in the filename, then the port number must be prefixed with -p, It is recommended that you always prefix the port number with -p. aem-,aem-

Set up secondary run modes:-

There are two ways to setup secondary or environment specific run modes:-

Using Sling Properties file:-
  • Go to  <cq-installation-dir>/crx-quickstart/conf/
  • Add the following properties (below example is for author, dev)
  • In above case will get picked up
    Note:- If this node is not found then will be picked, and the config node

In nut shell we can provide a comma separate list of run modes. For example author,dev,en. If no standard mode is specified CQ assumes it is author mode through quickstart.

Using System Properties or JVM Arguments:-
  • Go to <cq-installation-dir>/crx-quickstart/conf/ and system property (In start script):
  • In sling property file add
      Note:- This is because there is bug in AEM that by default this regex is set up for author.
  • In start up script use
    • java -Xmx512m -jar aem-quickstart-6.1.jar,prod
  • In above case will get picked up
    Note:- If this node is not found then config.publish will be picked, and the config node

Now the quick question that arises in our mind is – What will happen if i define run modes by both types sling properties and system properties? which will take precedence?

Following is the order of precedence for run mode (From top to bottom, Top being highest)

  1. From jar file  — Custom or secondary run modes not supported.
  2. From System property(-D) (,prod,test3 )
  3. From -r option (java -jar cq-56-p4545.jar -r author,test2)
  4. From Sling property —  At starting this file is not available.
    1. Create crx-quickstart folder parallel to your jar file
    2. Inside it create config folder.
    3. inside it  create file.
    4. add below line to it,test1.

Note:- Go your your command prompt and start the aem jar ( It should not have primary run mode in its name else it will take priority).

Create run modes:-

Lets take a use case for understanding run modes better. For example by default the log level is set as information but you want that on development environment it should be Debug. In order to accomplish it lets add a run mode for development environment. Follow below steps to create run modes in aem.

  • Go to Crxde.
  • Go to /apps/<myproject>/.
  • Create folder runmodes.
  • Under runmodes create folder Make sure the is of type sling:Folder.create config runmode folder
  • Create a node of type sling:OsgiConfig under the folder. Node name should be the same name as the Persistent Identity (PID) of the configuration in the OSGi Console.
    • Go to Felix console config manager and search for Apache Sling Logging Configuration.
      aem logging configuration property
      aem osgiconfig configuration node
  • Add property on for changing log level specific to environment.
    aem logging configuration
  • Now restart the instance by giving,dev JVM argument.
    • java -XX:MaxPermSize=256m -Xmx1024M -jar AEM_6.1_Quickstart-author-4502.jar,dev
  • Go to Felix console configuration, open Apache Sling Logging Configuration. Your run mode should be updated to debug.

verify runmode configuration


Spread the love

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.