Local Development with Cloud Manager Variables

Cloud Manager Variables are the preferred method for managing and storing credentials and other sensitive information in Adobe Experience Manager as a Cloud Service.

But that’s not the only use for Cloud Manager Variables. They also help developers manage configurations across environments without modifying the codebase. During local development, applications often rely on settings (such as API endpoints or authentication keys) different from those used in production. While the code stays the same, the application’s behavior can differ significantly based on these environment-specific configurations.

Cloud Manager Variables allow developers to define these values once, manage them outside the codebase, and ensure each environment runs with the correct context. This means fewer misconfigurations and can improve speed to market.

In this post, we'll explain how to use environment-specific variables effectively to avoid issues during local development.

Using Cloud Manager Variables in Local Development

For context, Cloud Manager Variables are "deployed" into the same container where the AEM instance runs, making them available at runtime. The application then takes the necessary steps to access these variables.

Since Cloud Manager handles the exposure of variables at runtime, there are no issues when the application runs in Cloud Manager environments. However, this is not the case in local development.

Cloud Manager Environment-Specific Variables

Similar to the environment that Cloud Manager creates, these variables must be available similarly to our local environment. The key is to expose any (non-secret) Cloud Manager variable as an environment variable on our local machines.

For example, if we have an OSGi config that looks like this:

{
 "url": "$[env:MY_URL]"
}

In our local environment, we need to ensure that this is available at runtime, meaning it needs to be accessible in the context where AEM is running. If you're using a command to start your AEM server, such as java -jar aem-author-p4502.jar, you'll likely need to make sure that the variable MY_URL is available from the same terminal window. If you start AEM via the UI, the variable probably needs to be set globally.

If you are using macOS or Linux, you can do something like this:

# Set the variable
export MY_URL = "http://the-value-of-the-variable-goes-here"

There are a couple of ways to set environment variables in Windows. However, you only need to know that you must set this up and ensure it is available in the context where AEM is started.

Cloud Manager Secrets

Because these variables contain sensitive information, they are not stored as environment variables. Instead, they are treated as plain files without extensions. Similarly, the application makes the necessary adjustments to read the information from each file. The key here is creating files in a location that the AEM server knows.

For example, if we have an OSGi config that looks like this:

{
 "my_password": "$[secret:MY_PASSWORD]"
}

In our local environment, we need to create a file called my_password (without an extension) and store the value of the secret within it. It’s usually a good practice to create a folder within crx-quickstart and name it secretdir, but it could be any folder located anywhere on our filesystem.

Then, we tell AEM where to find the folder that contains all the secret variables. Remember that you cannot have multiple directories; all the secrets must be stored in the same folder. To do this, we need to update the crx-quickstart/conf/sling.properties file and add the following line:

org.apache.felix.configadmin.plugin.interpolation.secretsdir=${sling.home}/secretsdir

Note that the value of ${sling.home} is the location of the crx-quickstart folder. If you created the secrets folder elsewhere on your system, update this value accordingly.

Setting Up Variables Efficiently

Now that we understand how to use Cloud Manager variables, how can we manage them effectively? Several factors must be considered, such as the operating system, the number of variables, their purpose, etc. Below, we’ll propose a couple of alternatives for easier management.

1. Setting Default Values for the Variables

Setting default values for variables is a best practice. In some scenarios, having a default value can prevent errors or unexpected behavior, especially when a variable is not explicitly set in certain environments. Default values help ensure that your application has a fallback option and can continue functioning correctly, even if some variables are missing or misconfigured. Of course, this cannot be applied to all the cases or all the variables, but use it as much as you can.

For example:

{
 "url": "$[env:MY_URL];default=localhost"
}

2. Manually Adding Environment Variables

This is typically the default approach, but it’s best considered when the number of variables is relatively small. Another scenario where this option might be suitable is when a fully local environment isn't necessary. Although it might seem unusual, this could be a common pattern. For example, if you're working on a project where testing Analytics locally isn’t required, there’s no need to configure Analytics or set the associated environment variables.

3. Automating the Environment Creation

If you have many critical variables and cannot use default values, you might consider creating a bash script that runs before the AEM instance starts. You can define all the variables within this script and instruct your developers to execute it before launching the AEM server. This approach makes it easier to manage the variables in a single script file that can be shared as needed.

Something like this:

#!/bin/bash

# Set environment variables
export VAR_1 = value1
export VAR_2 = value2
...
export VAR_X = valueX

# Print the variables to verify
echo "VAR_1 is set to: $VAR_1"
echo "VAR_2 is set to: $VAR_2"
...
echo "VAR_3 is set to: $VAR_4"

4. Versioning the Variables

Finally, if you’re managing variables that are safe to be shared with everyone who has access to your source code management (SCM) system, you can simply add a variables script or include the values directly in your codebase. Remember that your code is already protected by the access controls of your SCM, providing an additional layer of security to ensure that only authorized individuals can access the variables.

Wrapping Up

Cloud Manager Variables are excellent for storing crucial information in AEM. However, they can sometimes be a headache for developers who need to implement changes on top of functionality that depends on these variables. Using them effectively involves selecting the right type of variable and managing it efficiently throughout the development lifecycle.

Oshyn is an Adobe partner that can help you get the most out of your AEM investment and features like Cloud Manager Variables. Our developers leverage their experience, best practices, and diligence to ensure your Adobe Experience Manager site is implemented to the highest standards.

Learn more about getting more out of AEM in our ebook: Adobe Experience Manager Content Editing Best Practices.