Adobe Experience Manager - configure OSGI Configurations

In this article, we are going to discuss the different ways to add configurations into the AEM instance. Technically there are four simple ways to add configurations into an AEM instance, in this article in addition to the explanation for the different types I included a few examples for each to help with the implementation in your projects.

Technical details and Assumptions:

All the following details are tested in AEM version 6.5.8, Java version 11.0.2

Across this article, I am assuming that you have already created a custom config to configure or just updating a default configuration that's built-in AEM as out-of-box configurations.

To create a new OSGi configuration, check my other article about it here.

Different methods to add configurations:

The implementation types are listed below,

1) Configuring manually in the web console

To add a configuration using this implementation, you will have to navigate to the following URL,

<base-url>/system/console/configMgr

An example URL will look like this,

http://localhost:4502/system/console/configMgr

A little unfortunate that this web console does not have an inbuilt search system. We can just use the browser's page-level search function using Ctrl + F. Once we get a hold of which config to update, the update is straightforward.

 

 

For explaining purposes I am using the default Apache logger (Apache Sling Logging Logger Configuration). I chose a config with multiple configurations in this example so that, both single and multiple configurations can be explained.

The plus icon helps to create a new configuration.

For editing the configurations, you can either click on the pen icon or the entire row to open the overlay which helps to update the configurations. this overlay looks like the follows,

 

The necessary changes can be made and saved to be reflected in the AEM instance. Similarly, we have a delete and unbind option which can help to remove the config temporarily or permanently.

2) Add configurations to the codebase

In this type of implementation, we tend to add the configuration specific to the project that uses the configuration. 

If you are looking for an out-of-the-box configuration you can look into the following hierarchy with a repository node of type sling:OsgiConfig,

/libs/*/config/

If you are planning to create a new configuration entry or update one that has already been added, you can check under the following hierarchy with a repository node of type sling:OsgiConfig or property files,

/apps/*/config

Now let's check now the configurations can be arranged and categorized, One main way to do that is based on the run-modes. Please feel free to look into the official AEM documentation here. Usually, inside your project folder under /apps folder, the configurations are placed.

The folder names are given based on the run mode, AEM prioritization is based on how specific the configuration is written to the given AEM instance.

/config/

/config.dev/

/config.dev.author/

/config.stage/

/config/stage.publisher/

As long as the configs are placed under a folder that has a naming similar to the above and is under /apps folder, the configs should be loaded into the AEM instance.

Specs of the configuration file:

Diving into the specs of the config file, here for explaining the steps I and using the following email configuration com.day.cq.mailer.DefaultMailService

a) the name of the configuration file should be in the following format,

<class-name>.xml

A sample configuration file name would look like this,

com.day.cq.mailer.DefaultMailService.xml

Note: if the implementation class is implemented via interface.classname will be the interface name otherwise it will be an implementation class.

b) the XML file should look like the following,

	<?xml version="1.0" encoding="UTF-8"?>
	<jcr:root xmlns:sling="http://sling.apache.org/jcr/sling/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0"
	jcr:primaryType="sling:OsgiConfig"
	debug.email="{Boolean}false"
	smtp.port="{Long}25"
	smtp.user="you-know-i-cannot-say-this-here"
	smtp.ssl="{Boolean}false"
	from.address="mostly-your-mail-id"
	smtp.host="whatever-your-host-says"
	/>

view raw com.day.cq.mailer.DefaultMailService.xml hosted with ❤ by GitHub

Just building the code with this XML in it will help to load the configurations automatically

3) Add configuration as a package:

This implementation allows adding configurations that are both project-specific and non-project-specific. For adding project-specific configurations please follow the same steps below with the hierarchy in the previous section. Adding non-project-specific configurations should be done to the following path,

/apps/system/config/

The config should be added as a .config file and should be of the following structure,

	debug.email="{Boolean}false"
	smtp.port="{Long}25"
	smtp.user="you-know-i-cannot-say-this-here"
	smtp.ssl="{Boolean}false"
	from.address="mostly-your-mail-id"
	smtp.host="whatever-your-host-says"

view raw com.day.cq.mailer.DefaultMailService.config hosted with ❤ by GitHub

and install it using the package manager (http://localhost:4502/crx/packmgr/index.jsp).

If you are not sure how to create a package, you can just export a file in that folder and download it to your local. You can examine the structure there and reuse the same.

4) Add configurations directly to the AEM instance:

This implementation allows placing the files under the crx-quickstart folder and these config files are loaded into the AEM instance while starting. If the AEM instance is up and running, to see the changes you will have to restart the instance to see the changes. 

The config must be placed in the following path,

<*cq-installation-dir*>/crx-quickstart/launchpad/config/

The configurations should be in the following format,

	:org.apache.felix.configadmin.revision:=L"1"
	debug.email=B"false"
	from.address="mostly-your-mail-id"
	service.pid="com.day.cq.mailer.DefaultMailService"
	smtp.host="whatever-your-host-says"
	smtp.port=L"25"
	smtp.ssl=B"false"
	smtp.user="you-know-i-cannot-say-this-here"

view raw DefaultMailService.config hosted with ❤ by GitHub

Which one takes priority?

the order of precedence can be categorized into two based on whether its run-time/startup,

order of precedence during startup:

1) Repository nodes under /apps/*/config....either with type sling:OsgiConfig or property files.
2) Repository nodes with type sling:OsgiConfig under /libs/*/config.... (out-of-the-box definitions).
3) Any .config files from <*cq-installation-dir*>/crx-quickstart/launchpad/config/.... on the local file system.

order of precedence during run-time:

1) Modifying a configuration in the Web console will take immediate effect as it takes precedence at runtime.
2) Modifying a configuration in /apps will take immediate effect.
3) Modifying a configuration in /libs will take immediate effect unless it is masked by a configuration in /apps.

When to use what?

Now that we know that AEM allows us to install our configs in 4 different ways, Let's go through some scenarios and discuss the pros and cons for each of these ways to achieve our goal. 

Configuring manually in the web console:

- This is the simplest way to add an OSGi configuration. 

- Being the simplest and manual way, takes a lot of time to perform this method when there is a large number of environments.

- Being manual, this method can make room for the different human errors (missing to configure some instances, missing to configure some OSGi configurations in an instance, Typo errors and etc)

Adding configurations via codebase:

- This implementation eliminates some concerns related to human errors that we had while manually configuring them.

- This implementation is preferred for configurations that are project-specific and non-sensitive in nature

- This implementation opens new concerns for sensitive data/credentials that are configurable. Since having sensitive data in the codebase can increase the risk of those data being exposed. Primarily because lots of people have access to it (Developer, DevOps, QA, and other different levels of people).

Adding configurations as a package:

- This implementation eliminates the risk of having sensitive data in the codebase.

- This implementation is partially manual work too since one person has to create the package by manually configuring in an instance and exporting the same to manually install the package to every AEM instance in the environment. But reduces possible human error to just missing configuration in environments and eliminates the other human errors like Typo.

- One thing to notice is that we might need to have appropriate write permission in the AEM instance we want to install into. Usually, normal users will not have them in higher environments.

Adding configurations directly into the AEM instance:

- This implementation is almost similar to installing as a package when weighing its pros and cons.

- It eliminates the sensitive data in codebase issue. It is partially manual in placing the file to each of the instances.

- The main thing to notice here is that for proceeding with this approach we will need write access to the server in which we deploy the AEM instance. This permission is even rarer than the AEM admin permissions.

- To see the changes in effect, the AEM instance has to be restarted.

For installing sensitive configurations, the last two approaches are both fine to use. I personally prefer the last approach, since it's a little clean and simple to directly place the config file. While installing a package you will have to create it in package format every time you change the data. Still, it's my personal preference :P

If you have tried any new approaches or new variations of the approaches feel free to share in the comments ❤️

Thanks for reading :)

References:

1) https://experienceleague.adobe.com/docs/experience-manager-65/deploying/configuring/configure-runmodes.html?lang=en