{"id":20509175,"url":"https://github.com/shinesolutions/aem-orchestrator","last_synced_at":"2025-06-27T14:03:30.460Z","repository":{"id":17961878,"uuid":"78390880","full_name":"shinesolutions/aem-orchestrator","owner":"shinesolutions","description":"Java application for orchestrating AEM infrastructure created using aem-aws-stack-builder","archived":false,"fork":false,"pushed_at":"2024-05-07T05:20:48.000Z","size":465,"stargazers_count":12,"open_issues_count":3,"forks_count":9,"subscribers_count":12,"default_branch":"master","last_synced_at":"2025-04-13T22:39:25.830Z","etag":null,"topics":["aem","aem-opencloud","auto-recovery","orchestration","self-healing"],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shinesolutions.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-01-09T03:36:16.000Z","updated_at":"2024-05-07T05:20:51.000Z","dependencies_parsed_at":"2024-05-07T06:27:54.634Z","dependency_job_id":"ea271de7-418a-416d-b414-6f0d43ed8447","html_url":"https://github.com/shinesolutions/aem-orchestrator","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/shinesolutions/aem-orchestrator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shinesolutions%2Faem-orchestrator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shinesolutions%2Faem-orchestrator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shinesolutions%2Faem-orchestrator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shinesolutions%2Faem-orchestrator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shinesolutions","download_url":"https://codeload.github.com/shinesolutions/aem-orchestrator/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shinesolutions%2Faem-orchestrator/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262269886,"owners_count":23285157,"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","aem-opencloud","auto-recovery","orchestration","self-healing"],"created_at":"2024-11-15T20:22:59.202Z","updated_at":"2025-06-27T14:03:30.415Z","avatar_url":"https://github.com/shinesolutions.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://github.com/shinesolutions/aem-orchestrator/workflows/CI/badge.svg)](https://github.com/shinesolutions/aem-orchestrator/actions?query=workflow%3ACI)\n\n# AEM Orchestrator\nAEM Orchestrator is a stateless Java application for orchestrating AEM infrastructure created using [aem-aws-stack-builder](https://github.com/shinesolutions/aem-aws-stack-builder). It's primary function is to keep Adobe Experience Manager (AEM) running in a healthy state despite scaling events or other such impacts on the stack. It does this by listening to a predefined SQS queue and reacting to changes on the stack.\n\n\n## Build\n\nThis project requires Java 8 to compile and run the source code. Apache Maven 3.3 was used as the build tool.\n\n### Create JAR file\n```\n$ mvn clean package\n```\nThis will create a JAR file in the '\\target' directory called aem-orchestrator-x.x.x.jar. \nBy default the generated JAR file will contain all of the required dependencies\n  \n\n## Usage\n### Requirements\nThe AEM Orchestrator requires [aem-aws-stack-builder](https://github.com/shinesolutions/aem-aws-stack-builder) to have created a stack in order to work. You'll need to get this running before attempting to run AEM Orchestrator. If using puppet then you should also take a look at [puppet-aem-orchestrator](https://github.com/shinesolutions/puppet-aem-orchestrator).\n\nThe AEM Orchestrator uses [AWS Instance Profiles](http://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2_instance-profiles.html) authentication. If you do not already have this, you will need to set it up.\n\nThe application requires there to be an application.properties file in the same base directory as the JAR file. Here is an example of a properties file with the minimum properties set:\n\n```properties\naws.cloudformation.stackName.author = example-aem-author-stack\naws.cloudformation.stackName.authorDispatcher = example-aem-author-dispatcher-stack\naws.cloudformation.stackName.publish = example-aem-publish-stack\naws.cloudformation.stackName.publishDispatcher = example-aem-publish-dispatcher-stack\naws.cloudformation.stackName.messaging = example-aem-messaging-stack\naws.sqs.queueName = example-aem-asg-event-queue\n```\n\nThe aem-aws-stack-builder will generate these names for you, they just need to be added to this Orchestrator application.properties file. See [here](docs/configuration.md) for more information on configuration properties. You can also view the base [application.properties](src/main/resources/application.properties) file.\n\n### Running the JAR\nThe JAR file is created as a 'fully executable' jar. See Spring Boot [deployment and install](http://docs.spring.io/spring-boot/docs/current/reference/html/deployment-install.html).\nThere are two ways to run the JAR:\n\n```\n$ java -jar aem-orchestrator-x.x.x.jar\n```\n\nor as a 'fully executable' direct application (only works on Unix/Linux based systems):\n\n```\n$ ./aem-orchestrator-x.x.x.jar\n```\n\n### Logging\nBy default the Orchestrator will log to a file called *orchestrator.log* in the root directory. It uses [logback](https://logback.qos.ch/) and here is the default [configuration file](src/main/resources/logback.xml). Note that debug is enabled by default. To override the default logging, place your custom logback.xml file in the same directory as the JAR file.\n\n\n## Functionality\nThe AEM Orchestrator reacts to three different types of events:\n\n1. [Instance Scale Up](docs/scale-up-events.md)\n2. [Instance Scale Down](docs/scale-down-events.md)\n3. [Alarms](docs/alarms.md)\n\n### Scale Events\nThe scale up and scale down events are generated by the AWS autoscaling groups (ASG). These can occur at the following tiers of the stack:\n\n* Author Dispatcher\n* Publish\n* Publish Dispatcher\n\nFor example if a Publish instance stopped responding the ASG would terminate it, which would generate a message to the Orchestrator to perform a *Scale Down Publish Action*. The ASG would also start a new Publish instance, which would generate a *Scale Up Publish Action*. In each case, the AWS instance ID is passed to the Orchestrator so that it can perform it's action.\n\n### Alarms\nCurrently there is only one alarm, the [AEM Content Health Check](https://github.com/shinesolutions/aem-aws-stack-provisioner/blob/master/templates/aem-tools/content-healthcheck.py.epp). This will trigger if the Publish Dispatcher is not seeing healthy content (defined in a [descriptor file](https://github.com/shinesolutions/aem-aws-stack-provisioner/blob/master/examples/content-healthcheck-descriptor.json)) on the Publish instance. When the alarm triggers the Orchestrator is notified via an SQS message and it will perform an *Alarm Content Health Check Action*.\n\n### Recovery\nAside from stack startup, the AEM Orchestrator is designed to recover the stack from multiple scenarios:\n\n* Termination of a single instance (Author Dispatcher, Publish or Publish Dispatcher)\n* Termination of many or all instances\n* Scale up of a single instance (Author Dispatcher, Publish or Publish Dispatcher)\n* Scale up of all instances\n\n**NOTE**: The AEM Orchestrator must be running to perform this recovery, however due to it's stateless nature, the AEM Orchestrator can be started post termination or scale up of an instance. Upon startup, it will begin processing messages off the SQS queue. In essence the queue holds the state of the stack not the AEM Orchestrator.\n\n### Reading Messages\nThe AEM Orchestrator attaches itself as a listener to the SQS queue defined in the application.properties. It works in an asynchronous manner and does **not** poll the queue. If the Orchestrator fails to perform an action on a message for what ever reason, the message will not be acknowledged and instead kept in flight on the queue to be reprocessed at a later time. Only one message is processed at a time (no concurrency). There is no guarantee to the order of processing, but the Orchestrator is designed to handle messages in any order.\n\nThe message format is the Amazon SNS [HTTP/HTTPS Notification JSON Format](http://docs.aws.amazon.com/sns/latest/dg/json-formats.html). A JSON definition of the format can be found [here](https://sns.us-west-2.amazonaws.com/doc/2010-03-31/Notification.json).\n\n\n## Troubleshooting\nIf all goes well at start up you should see something like this in your log file:\n\n```\nDEBUG c.s.a.s.OrchestratorMessageListener - Initialising message receiver, starting SQS connection\nINFO  c.s.aemorchestrator.AemOrchestrator - AEM Orchestrator started\n```\nOtherwise you will need to view the *orchestrator.log* and try and decipher what is going wrong. Most likely causes are:\n\n* Stack not properly initialised\n* Invalid or missing IAM role permissions\n* Invalid or missing property in the application.properties file\n* AEM not in a healthy state on author or publish instances\n* AWS Instance Profile authentication not set up\n\n### How do I know it's working?\nUpon startup of the stack you will see the Orchestrator log showing the processing of many messages. Here is a log example (with debug off) for a *Scale Up Publish Dispatcher Action*:\n\n```\nINFO  c.s.a.s.OrchestratorMessageListener - Message received ID:3dfea271-254c-4cef-a793-ff67a2218239\nINFO  c.s.a.a.ScaleUpPublishDispatcherAction - ScaleUpPublishDispatcherAction executing\nINFO  c.s.a.a.ScaleUpPublishDispatcherAction - Desired capacity already matching for publish auto scaling group and it's dispatcher. No changes will be made\nINFO  c.s.a.s.OrchestratorMessageListener - Acknowledged message (removing from queue): ID:3dfea271-254c-4cef-a793-ff67a2218239\n```\n\nIf the Orchestrator log isn't moving but there are definitely messages in the SQS queue, then something may be wrong (refer to likely causes above). ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshinesolutions%2Faem-orchestrator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshinesolutions%2Faem-orchestrator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshinesolutions%2Faem-orchestrator/lists"}