{"id":20020678,"url":"https://github.com/netcentric/system-env-install-hook","last_synced_at":"2025-05-05T01:30:43.295Z","repository":{"id":52541713,"uuid":"116678593","full_name":"Netcentric/system-env-install-hook","owner":"Netcentric","description":"Elastic AEM instances made easy.","archived":false,"fork":false,"pushed_at":"2021-04-26T18:10:33.000Z","size":117,"stargazers_count":8,"open_issues_count":6,"forks_count":3,"subscribers_count":29,"default_branch":"develop","last_synced_at":"2025-04-08T14:41:20.561Z","etag":null,"topics":["aem","configuration-management","osgi-configurations","replication","zookeeper"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"epl-1.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Netcentric.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-01-08T13:13:23.000Z","updated_at":"2024-12-09T19:55:00.000Z","dependencies_parsed_at":"2022-08-25T23:10:55.545Z","dependency_job_id":null,"html_url":"https://github.com/Netcentric/system-env-install-hook","commit_stats":null,"previous_names":["netcentric/apply-system-env-install-hook"],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Netcentric%2Fsystem-env-install-hook","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Netcentric%2Fsystem-env-install-hook/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Netcentric%2Fsystem-env-install-hook/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Netcentric%2Fsystem-env-install-hook/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Netcentric","download_url":"https://codeload.github.com/Netcentric/system-env-install-hook/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252422932,"owners_count":21745515,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aem","configuration-management","osgi-configurations","replication","zookeeper"],"created_at":"2024-11-13T08:33:38.132Z","updated_at":"2025-05-05T01:30:42.946Z","avatar_url":"https://github.com/Netcentric.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"Apply Env Install Hook for AEM/CRX\n================================================\n\n**DISCLAIMER:**\nThis hook should be used sparsely for very limited use cases only. Almost all OSGi configurations should be bound to runmodes as well-established mechanism to configure different environments. However reasonable use cases are:\n\n* Replication Agents (if the set of potential target environments is unlimited/unknown)\n* Cloud Configurations with differing values (e.g. URLs) between different environments\n* OSGi configurations that differ per env (e.g. for a AEM communities user sync)\n* Sensitive production passwords (in OSGi configurations or cloud services) that have to be deployed automatically (this can be mitigated by using the CryptoService and a well-defined master key, however if the master key leaks all passwords can be decrypted) \n\nFor OSGi configurations, Felix recently introduced the configadmin plugin [interpolation](https://github.com/apache/felix-dev/tree/master/configadmin-plugins/interpolation) that allows for env variables substitution on framework level, however there is no out-of-the-box platform solution to apply env variables to content.\n\n# Overview\n\nReplaces variables in content packages for files (e.g. useful for OSGi configurations) and node properties (e.g. useful for replication agents).\n\nVariables can be in form `${myVar}` or  `${myVar:defaultVal}` - if the var can not be found in any sources, for the first example `${myVar}` remains as is, for the second example `defaultVal` is used.\n\n# Configuration\n\n## Including variables in packages\n\n### Nodes with suffix .TEMPLATE\n\nAdditionally to nodes that explictly configured to be adjusted, any nodes that end with `.TEMPLATE` will be copied to the same name without `.TEMPLATE` (e.g. `/etc/path/to/configfile/com.example.MyService.config.TEMPLATE` will be copied to `/etc/path/to/configfile/com.example.MyService.config` with the values replaced). To avoid that a configuration is deleted upon regular package installation, the target node (without `.TEMPLATE`) has to be excluded via exclude rule of filter statement. \n\nExample:\n\n* Node to be added: `/etc/replication/agents.author/publish`\n* Node contained in the package: `/etc/replication/agents.author/publish/jcr:content.TEMPLATE` (don't include `/etc/replication/agents.author/publish/jcr:content`!)\n* Filter rule with exclude (to ensure it is not deleted because it's not in package): \n```\n/etc/replication/agents.author/publish\n  \\- exclude /etc/replication/agents.author/publish/jcr:content\n```\n\n\n### Package Property applySystemEnvForPaths\n\nAlternatively, the vault package property `applySystemEnvForPaths` can be given to explicitly list properties and files where the replacement shall take place (opposed to use the automatic `.TEMPLATE` mechanism described above):\n\n```\n/etc/path/to/node/jcr:content@testValue,\n/etc/path/to/node/jcr:content@testValueOther,\n/etc/path/to/configfile/com.example.MyService.config\n```\n\nMultiple values can be given separated by whitespace and/or comma. This approach has the downside that nodes are \"double-saved\" (first one on package installation itself, second one on install hook phase `INSTALLED` with replaced parameters).\n\n\n## Variable Value Sources\n\nThe package property `applySystemEnvSources` is used to defined sources (default: `SystemProperties,JCR,OsEnvVars`). For each variable each source is asked, the first source that resonds with a value will be used (the installation log in Package Manager clearly logs where variable values come from).\n\n### Source \"OsEnvVars\"\n\nWill use the immutable system environment as provided by the OS. All values with `.` have to be set with `_` as dots are not allowed as environment variables (e.g. `my.test.var` as set in package has to be set as env variable `my_test_var`). \n\n### Source \"JCR\"\n\nReads the node `/etc/system-env` and uses all its properties to set the variables. This is particular useful to be used for CI/CD tools like Jenkins to easily set values via REST (Sling POST Servlet).\n\nIf the node `/etc/system-env` does not exist, this source is ignored (no error is thrown).\n\nNOTE: Obviously Jenkins could also post to the actual config locations and change them in place. However then Jenkins has to re-send a lot of boilerplate around the few values that are actually env-specific. Also the paths may be scattered all around the repo which makes the Jenkins-side unnecessarily complicated. Using apply-system-env-install-hook with values from /etc/system-env clearly separates \"regular config\" from system-env.\n\n### Source \"ZooKeeper\"\n\nConfiguration variables for a whole environment can be maintained in ZooKeeper and automatically be consumed by multiple AEM instances (e.g. author cluster + 4 publishers).\n\nTo configure ZooKeeper itself, the following JRE System Parameters have to be set (along with the source in the package):\n\n* `applysysenv.zookeeper.hosts` (required): the ZooKeeper hosts (e.g. `localhost:2181,localhost:2182,localhost:2183`\n* `applysysenv.zookeeper.path` (required):  The path where the config resides, e.g. `/configs/aem-env.properties`. \n* `applysysenv.zookeeper.overrideSuffix` (optional): This is useful if some properties are different for only one particular instance (while `aem-env.properties` describes all instances of an environment) - e.g. for replication, if publishers have their own flush url, `replication.publish.flushUrl@publish1` and `replication.publish.flushUrl@publish2` can be used (while e.g. publish1 would have the system property `applysysenv.zookeeper.overrideSuffix=publish1` set)\n\nOne way of loading a file into ZooKeeper is using `zkCli.sh`: \n```\nzkCli.sh set /configs/aem-env.properties \"`cat aem-env.properties`\"\n```\n\nIf the source `ZooKeeper` is configured in package, but `applysysenv.zookeeper.hosts` or `applysysenv.zookeeper.path` is not set, a warning is logged an the source will not provide any values.\n\nAlso, for this source to work the zookeeper jar has to be put in crx-quickstart/install (or be installed via a different means).\n\n### Source \"SystemProperties\"\n\nWill use system properties to set variables. Mostly useful for manual intervention, hence first source in default setting of `applySystemEnvSources`.\n\n\n# Using The Install Hook in a Package\nEnsure the hook ins copied into the package:\n\n```\n    \u003cplugin\u003e\n        \u003cgroupId\u003eorg.apache.maven.plugins\u003c/groupId\u003e\n        \u003cartifactId\u003emaven-dependency-plugin\u003c/artifactId\u003e\n        \u003cversion\u003e3.0.2\u003c/version\u003e\n        \u003cexecutions\u003e\n            \u003cexecution\u003e\n                \u003cid\u003ecopy-hook-into-package\u003c/id\u003e\n                \u003cphase\u003egenerate-resources\u003c/phase\u003e\n                \u003cgoals\u003e\n                    \u003cgoal\u003ecopy\u003c/goal\u003e\n                \u003c/goals\u003e\n                \u003cconfiguration\u003e\n                    \u003cartifactItems\u003e\n                        \u003cartifactItem\u003e\n                            \u003cgroupId\u003ebiz.netcentric.aem.sysenvtools\u003c/groupId\u003e\n                            \u003cartifactId\u003eapply-system-env-install-hook\u003c/artifactId\u003e\n                            \u003cversion\u003e1.2.0\u003c/version\u003e\n                        \u003c/artifactItem\u003e\n                    \u003c/artifactItems\u003e\n                    \u003coutputDirectory\u003e${project.build.directory}/vault-work/META-INF/vault/hooks\u003c/outputDirectory\u003e\n                \u003c/configuration\u003e\n            \u003c/execution\u003e\n        \u003c/executions\u003e\n    \u003c/plugin\u003e\n            \n```\n\nConfigure it via vault package properties:\n\n\n```\n    \u003cplugin\u003e\n        \u003cgroupId\u003ecom.day.jcr.vault\u003c/groupId\u003e\n        \u003cartifactId\u003econtent-package-maven-plugin\u003c/artifactId\u003e\n        \u003cversion\u003e0.5.1\u003c/version\u003e\n        \u003cextensions\u003etrue\u003c/extensions\u003e\n        \u003cconfiguration\u003e\n            \u003cgroup\u003eNetcentric\u003c/group\u003e\n            \u003cfilterSource\u003esrc/main/META-INF/vault/filter.xml\u003c/filterSource\u003e\n            \u003cproperties\u003e\n                \u003capplySystemEnvSources\u003eSystemProperties,ZooKeeper,OsEnvVars\u003c/applySystemEnvSources\u003e\n                \u003c!-- paths to adjust, can be left out if '.TEMPLATE' paths are used --\u003e\n                \u003capplySystemEnvForPaths\u003e\n                    /etc/path/to/node/jcr:content@testValue,\n                    /etc/path/to/node/jcr:content@testValueOther,\n                    /etc/path/to/configfile/com.example.MyService.config\n                \u003c/applySystemEnvForPaths\u003e\n                \u003c!-- default is false --\u003e\n                \u003cfailForMissingEnvVars\u003etrue\u003c/failForMissingEnvVars\u003e \n            \u003c/properties\u003e                    \n            \u003ctargetURL\u003ehttp://${crx.host}:${crx.port}/crx/packmgr/service.jsp\u003c/targetURL\u003e\n        \u003c/configuration\u003e\n    \u003c/plugin\u003e\n```\n\n# Troubleshooting for OS environment variable replacement \n\nThe environment variables need to be set to the env of the AEM process (since the install hook runs there). To check on OS-level if the\nenv was set correctly, the following command can be used:\n\n```\nsudo cat /proc/\u003cpid\u003e/environ | tr '\\0' '\\n' # if you know the pid\nsudo cat /proc/$(pgrep -f  quickstart.jar)/environ | tr '\\0' '\\n' # auto-query the pid \n```\n\nAlso, on AEM/JRE level the [Groovy Console](https://github.com/icfnext/aem-groovy-console) can be used to show the environment as the JRE gets to see it by running the following simple script:\n\n```\nSystem.getenv().each{ println it }\nreturn\n```\n\n# Automatically update changed configuration values in AEM\nWhen updating configuration values, normally they only become active upon **manual or automatically triggered re-installation** of configuration package that contains the `apply-system-env-install-hook`. \n\nHowever, when using the sources `ZooKeeper` or `JCR` it is possible to automatically reinstall the package containing the install hook.\n\nThis feature requires AEM 6.3.0 or higher\n\n## Install bundle system-env-change-listener \n\nInstall the bundle `system-env-change-listener-x.x.x.jar` to AEM. The easiest way to do this is to drop it in `crx-quickstart/install`.\n\n## Ensure the bundle system-env-change-listener may install packages\n\nCreate a service user (e.g. `sysenv-package-installer`) with permissions to install packages and create a user mapping as follows:\n`org.apache.sling.serviceusermapping.impl.ServiceUserMapperImpl.amended-sysenv-listener.config`\n\n```\nuser.mapping=[\"biz.netcentric.aem.sysenvtools.system-env-change-listener\\=sysenv-package-installer\"]\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnetcentric%2Fsystem-env-install-hook","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnetcentric%2Fsystem-env-install-hook","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnetcentric%2Fsystem-env-install-hook/lists"}