AEM Configuration Manager Across Environments
AEM Configuration Manager gives teams a practical way to control OSGi service settings without rebuilding the entire application for every deployment. In Adobe Experience Manager, these settings influence logging, schedulers, workflows, authentication handlers, replication agents, mail services, and integrations.
The real value appears when an organisation maintains separate development, testing, staging, and production environments. Each tier may use different endpoints, credentials, file paths, run modes, or performance limits, while the Java code remains the same.
For Australian AEM teams, this is especially relevant when systems span Sydney, Melbourne, Brisbane, or Perth operations, and when production workloads are hosted in an Australian cloud region. A configuration mistake can affect publishing during business hours, interrupt retail campaigns, or create delays for users working across different time zones.
A disciplined configuration strategy reduces those risks. It also makes deployments easier to audit, which matters to organisations handling customer information under Australian privacy expectations and to teams working with enterprise change-control processes.
How OSGi Configuration Works In AEM
AEM is built on OSGi, a modular Java framework in which services are registered and managed at runtime. Each service can expose configurable properties, such as a URL, boolean switch, timeout, cron expression, or maximum result count. AEM stores these properties as OSGi configuration data.
The Configuration Manager is available through the Felix Web Console, commonly at /system/console/configMgr. Administrators can search for a service, open its configuration screen, change values, and save the result. The interface is useful for diagnosis and controlled testing, but manual edits should not be the primary deployment method.
Configuration entries are identified by a PID, or persistent identifier. Some services use a single PID, while factory configurations can create multiple instances with separate names. Understanding the PID helps developers map a configuration screen to the corresponding Java service and to a file under the repository-based configuration structure.
A common mistake is treating configuration as application content. Content belongs to pages, assets, and repository structures; OSGi settings describe how the platform and its services operate. Keeping that distinction clear prevents environment-specific values from being mixed into content packages.
Separating Settings By Environment
AEM supports run modes that allow different configuration folders to apply to different instances. Typical run modes include author, publish, dev, stage, and prod, although the exact naming depends on the deployment design. A file under a more specific run-mode combination can override a more general configuration.
For example, a development author instance might use:
/apps/example/osgiconfig/config.author.dev/
A production publish configuration could live in:
/apps/example/osgiconfig/config.publish.prod/
The directory naming convention depends on the AEM version and deployment tooling, so teams should verify the supported structure for their platform release. The principle remains consistent: commit environment-aware configuration to source control, package it predictably, and deploy it with the application.
Use the same PID across environments where the service is conceptually the same, then vary only the properties that genuinely need to change. An API endpoint, queue size, log level, or feature flag may differ. A service class, interface contract, or security requirement generally should not be altered casually between tiers.
Australian businesses often have a separate user acceptance environment that mirrors production less closely than teams would like. Naming run modes clearly and documenting the differences helps prevent a Melbourne test system from accidentally calling a live customer service in Sydney or an overseas vendor endpoint.
Managing Configuration Through Source Control
Repository-based configuration is more reliable than clicking values into the Web Console. Store OSGi files in the AEM project, review changes through pull requests, and deploy them through the same pipeline used for Java bundles and content packages. This creates a record of who changed a value, why it changed, and when it was released.
Depending on the AEM version and project conventions, configuration may use .cfg.json, .config, or legacy .xml formats. Modern AEM projects commonly use JSON configuration, for example:
{
"enabled": true,
"timeout": 5000,
"serviceUrl": "https://api.example.com"
}
The filename must match the service PID and the file must be placed in the correct configuration folder. A typo in either area can leave the service using defaults or no configuration at all. Developers should inspect the generated package and confirm the deployed resource appears in the expected repository path.
Secrets require separate treatment. Passwords, client secrets, private keys, and tokens should not be committed to Git in plain text. Use the platform’s supported secret-management approach, deployment variables, protected pipeline values, or a managed secrets service. Configuration files can reference values supplied securely at deployment time where the architecture supports it.
For a site processing large image libraries, the relationship between OSGi settings and DAM operations is worth examining alongside asset processing profiles. Rendition generation, workflow queues, and processing limits can behave very differently in a developer laptop than in a production author environment.
Using The Configuration Manager Safely
The Felix Configuration Manager is valuable for checking the effective state of a running instance. It can show whether a configuration has been applied, which properties are active, and whether a service has generated an error. This makes it a strong diagnostic tool during a release or incident.
Manual changes through the console should generally be temporary and documented. A developer may adjust a log level to investigate a problem, or an operations engineer may disable a failing scheduler while protecting production. The permanent fix should then be applied to source-controlled configuration and redeployed.
After saving a configuration, inspect the service status, logs, and related functionality. A green-looking console entry does not prove that an external system is reachable or that a scheduled job is producing the expected result. Check authentication, network access, permissions, queue activity, and response times as appropriate.
Keep a practical rollback path. Configuration-only releases can still cause outages if they change connection pools, dispatcher behaviour, replication settings, or workflow concurrency. Tag the deployment, retain the previous package, and record any console intervention in the incident or change ticket.
Integrating External Services And Operational Controls
External integrations are a frequent reason for environment-specific OSGi configuration. A service may need a different base URL, client ID, scope, timeout, retry policy, or proxy setting in each tier. These values should be explicit and validated rather than hidden inside Java code.
OAuth settings deserve special care because a working token request does not necessarily prove that the requested scope or audience is correct. The OAuth integration guide is useful context when configuring third-party API access through AEM services.
Define sensible timeout and retry values. A short timeout can make a service appear unreliable when an upstream API is slow; an unlimited retry policy can exhaust AEM threads and make the broader platform unstable. Log failures without exposing access tokens, authorisation headers, or personal information.
Consider operational differences between environments. A production service may require a private network route, Australian data residency controls, or an approved outbound proxy. A local developer instance may need a mock server instead. Configuration should make those boundaries visible so that testing does not depend on accidental access to live infrastructure.
Testing And Troubleshooting Configuration Changes
Start by checking the package contents before deployment. Confirm the PID, file extension, run-mode folder, property names, and expected data types. Boolean values, arrays, factory configurations, and blank strings can all behave differently from what a developer expects.
Once deployed, use the Configuration Manager and OSGi console to verify the active configuration. Review error logs for activation failures, missing mandatory properties, invalid values, or unresolved service references. If a service does not start, inspect its dependencies rather than changing unrelated settings.
Test author and publish independently. A configuration that works on author may fail on publish because the service is not installed there, the network route differs, or the service requires permissions unavailable to the publish runtime. Dispatcher and CDN behaviour should also be tested when configuration affects caching or response headers.
For teams working in Australia, schedule production changes with local support coverage rather than relying on a US-based handover. A controlled release during a quieter Sydney or Melbourne window, with an agreed rollback owner and monitoring in place, is more useful than a technically perfect change made when nobody is watching the logs.
| Area | Recommended practice | Common risk |
|---|---|---|
| Storage | Keep configuration in the AEM project and source control | Untracked console changes |
| Environments | Use clear run modes for author, publish, test, and production | A test value reaching live services |
| Secrets | Inject credentials through protected secret mechanisms | Tokens committed to Git |
| Validation | Check active properties, logs, service status, and integrations | Assuming a saved form means success |
| Deployment | Package, review, release, and retain a rollback version | Configuration drift between instances |
| Operations | Record emergency console edits and reproduce them in code | Temporary fixes becoming permanent |
Treat Configuration Manager as a window into the running system, not as the system of record. Build environment-specific OSGi configuration into your delivery pipeline, review every sensitive change, and validate the effective settings on both author and publish instances. That approach gives AEM teams a clearer release trail and fewer surprises when a campaign, integration, or content operation goes live.