AEM Run Modes

Posted in AEM Tutorials By Raj On August 20, 2017


In this article, I am going to explain to you how to use run modes in AEM,  the run modes allows you to configure parameters specific to your environment, it is something like XML based configuration files which you use to store all configuration related information in any web application

We can build application without having run modes but, you need to think about maintenance and reusability, before building your application, you need question your self, are you going to deploy the same configuration in all the environment’s or not , if not then you must have run modes for you application

Let us take simple example, I think most of the people are familiar with SMTP configuration, to send an email from your AEM application or any web application you must-have SMTP port number, email address, password, and server address etc but, the problem here is the client is not ready to give a production credentials to test from your local or dev environment so, you must have something which allows you to configure things specific to particular environment, in AEM you can use run modes to solve this

The AEM is content management platform so, it always comes with author and publishing environment’s like any other content management system but, sometimes the requirement demands to execute specific functionality only either in author or publish, the best example is URL shortening build using custom transformation factory, this we need to execute only in publishing environment, if you execute this in author environment it will disturb your author environment by shortening all URL’s so you can not author pages, here you can use publish runmodes 

When you want to do some change in your configurations then it is not good practice to allow site admin to edit the configuration’s directly using config manager ( http://localhost:4502/system/console/configMgr ), it is easy to change configurations directly in the configMgr but, what about maintenance, you are allowing your administrator to touch QA or  production environment directly, what if something goes wrong ? so avoid touching configurations manually

It is good practice to deploy all configurations using run modes, but, if you use combination of both something like changing configurations manually  using configMgr and deploying the same through run modes then you will not have control on configurations whenever you do deployment it will override existing manual configurations so, dont do manual changes

If you are planning to deploy configurations through the code package then I recommend you to create a separate project only for configurations that will help you to deploy only configurations package instead of deploying entire code base

The below screen shot talks about sample run modes structure but, it varies based on your requirements, whatever configuration you put in config folder will execute for both the environments author and publish and remaining things are environment specific run modes


By default, there are four run modes AEM provides those are author, publish, samplecontent and nosamplecontent once you started you AEM with above run modes then you can not change it later, but you can change your custom run modes

  • author -> this is the run mode we use when we setup authoring environment
  • publish -> this is the run mode we use when we setup publishing environment
  • samplecontent -> this we use when you want to install sample content
  • nosamplecontent -> this we use only to setup production environment

If you see the above picture the which is a run mode for your development environment, this is a custom one you can change it at any time, but you need to restart your server to reflect the changes

Your environment can have combination of author with samplecontent or nosamplecontent or publish with samplecontent or nosamplecontent but, it should not be combination of author and publish or both samplecontent or nosamplecontent :

You can setup run modes by editing file, this file you can find under below location

edit file and add run mode property

The run modes configuration in the file shoule look like below


Starting AEM instance with run modes you can do with the command prompt also

I think most of the people are familiar renaming AEM jar file something like this cq5-author-4502.jar but this works only first time, next time onwards if you change author keyword to publish then it won’t work because this is OOTB installation run modes 

Creating run modes 

You can create run modes under your project folder, the best practice is to create a separate folder run modes under your project folder something like below 

Simple Feed Service Use Case:

I am going to build simple feed service, which allows you to configure feedUrl and feedId using Felix config manager if you see the below code, I am using OSGI annotations to read the feed URL and id

Feed Service class

I am going to create new class called “FeedServiceImpl” that implements FeedService and also it exposes getFeedUrl property that will read the feed url from the configurations

Once, you build above code and deploy it in your local environment then you will see empty values in the Felix configuration manager, what you need to do just populate this with default values using run modes for this I am going to create Sling:OsgiConfig node under config folder and add below properties


Once you completed above configuration, then if you go and see the configuration manager then you should see something like below



Change the feed Url and id and deploy the package once again and check it, the run modes will override existing manual authored configurations. so I strongly recommend you avoid changing configuration’s manually

In my component, I am reading run modes feed URL and displaying using below code, if you are looking for complete POC then download code

Download Run Modes Code


  • Dinh Tien Luyen

    Helpful blog. Would be better if you add ConfigurationPolicy at component level point where only provide configuration in the appropriate runmode