Merge pull request #24 from wttech/unified-instance-role

More representative instance role + local example

examples/controller/README.md

@@ -7,7 +7,7 @@
 
 Build a [Docker image](https://docs.docker.com/engine/reference/commandline/build/) being an [Ansible controller](https://docs.ansible.com/ansible/latest/network/getting_started/basic_concepts.html#control-node) with all dependent software installed.
 
-- Allows to execute Ansible on any operate system via containerizartion (including Windows which is not supported by Ansible natively)
+- Allows to execute Ansible on any operate system via containerization (including Windows which is not supported by Ansible natively)
 - Eliminates a need to perform OS-specific software installations (`brew install ansible` vs `apt-get install ansible`, etc)
 
 ## Prerequisites

examples/local/.gitignore

@@ -0,0 +1 @@
+aem_root/

examples/local/README.md

@@ -0,0 +1,21 @@
+![AEM Compose Logo](https://github.com/wttech/aemc-ansible/raw/main/docs/logo-with-text.png)
+[![WTT Logo](https://github.com/wttech/aemc-ansible/raw/main/docs/wtt-logo.png)](https://www.wundermanthompson.com/service/technology)
+
+[![Apache License, Version 2.0, January 2004](https://github.com/wttech/aemc-ansible/raw/main/docs/apache-license-badge.svg)](http://www.apache.org/licenses/)
+
+# AEM Compose - Ansible - Local Example
+
+Test just developed Ansible modules using lifecycle playbooks.
+
+## Prerequisites
+
+- Mac or Linux
+- Ansible 20.x and higher
+
+# Usage 
+
+Run command:
+
+```shell
+sh run.sh [start|provision|test|stop|destroy]
+```

examples/local/ansible.cfg

@@ -0,0 +1,20 @@
+[defaults]
+#debug = True
+log_path = ./ansible.log
+gathering = smart
+
+# nicer output formatting
+stdout_callback = debug
+callbacks_enabled = profile_tasks
+show_per_host_start = True
+bin_ansible_callbacks = True
+display_args_to_stdout = False
+display_skipped_hosts = False
+
+# others
+retry_files_enabled = False
+host_key_checking = False
+
+[ssh_connection]
+retries = 3
+pipelining = True

examples/local/destroy.yml

@@ -0,0 +1,11 @@
+---
+- name: Destroy instances
+  hosts: localhost
+  tasks:
+    - name: Kill instances
+      wttech.aem.instance:
+        command: kill
+
+    - name: Destroy instances
+      wttech.aem.instance:
+        command: destroy

examples/local/group_vars/all.yml

@@ -0,0 +1,214 @@
+---
+
+aem_root_dir: "{{ playbook_dir }}/aem_root"
+aem_home_dir: "{{ aem_root_dir }}/home"
+aem_tmp_dir: "{{ aem_home_dir }}/tmp"
+aem_lib_dir: "{{ aem_home_dir }}/lib"
+aem_tool_dir: "{{ aem_home_dir }}/opt"
+
+aem_instance_user: admin
+aem_instance_password: admin
+
+aem_author_active: true
+aem_author_ip: 127.0.0.1
+aem_author_http_url: "http://{{ aem_author_ip }}:4502"
+aem_author_debug_addr: 0.0.0.0:14502
+
+aem_publish_active: true
+aem_publish_ip: 127.0.0.1
+aem_publish_http_url: "http://{{ aem_publish_ip }}:4503"
+aem_publish_debug_addr: 0.0.0.0:14503
+
+aem_dispatcher_ip: 127.0.0.1
+aem_dispatcher_http_url: "http://{{ aem_dispatcher_ip }}"
+
+aem_config_dict:
+
+  # AEM instances to work with
+  instance:
+
+    # Full details of local or remote instances
+    config:
+      local_author:
+        active: "{{ aem_author_active }}"
+        http_url: "{{ aem_author_http_url }}"
+        user: "{{ aem_instance_user }}"
+        password: "{{ aem_instance_password }}"
+        run_modes: [ local ]
+        jvm_opts:
+          - -server
+          - -Djava.awt.headless=true
+          - "-Djava.io.tmpdir={{ aem_tmp_dir }}"
+          - "-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address={{ aem_author_debug_addr }}"
+          - -Duser.language=en
+          - -Duser.country=US
+          - -Duser.timezone=UTC
+        start_opts: [ ]
+        secret_vars:
+          - ACME_SECRET=value
+        env_vars:
+          - ACME_VAR=value
+        sling_props: [ ]
+      local_publish:
+        active: "{{ aem_publish_active }}"
+        http_url: "{{ aem_publish_http_url }}"
+        user: "{{ aem_instance_user }}"
+        password: "{{ aem_instance_password }}"
+        run_modes: [ local ]
+        jvm_opts:
+          - -server
+          - -Djava.awt.headless=true
+          - "-Djava.io.tmpdir={{ aem_tmp_dir }}"
+          - "-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address={{ aem_publish_debug_addr }}"
+          - -Duser.language=en
+          - -Duser.country=US
+          - -Duser.timezone=UTC
+        start_opts: [ ]
+        secret_vars:
+          - ACME_SECRET=value
+        env_vars:
+          - ACME_VAR=value
+        sling_props: [ ]
+
+    # Tuning performance & reliability
+    # 'auto'     - for more than 1 local instances - 'serial', otherwise 'parallel'
+    # 'parallel' - for working with remote instances
+    # 'serial'   - for working with local instances
+    processing_mode: auto
+
+    # State checking
+    check:
+      # Time to wait before first state checking (to avoid false-positives)
+      warmup: 1s
+      # Time to wait for next state checking
+      interval: 5s
+      # Number of successful check attempts that indicates end of checking
+      done_threshold: 3
+      # Wait only for those instances whose state has been changed internally (unaware of external changes)
+      await_strict: true
+      # Max time to wait for the instance to be healthy after executing the start script or e.g deploying a package
+      await_started:
+        timeout: 30m
+      # Max time to wait for the instance to be stopped after executing the stop script
+      await_stopped:
+        timeout: 10m
+      # Max time in which socket connection to instance should be established
+      reachable:
+        timeout: 3s
+      # Bundle state tracking
+      bundle_stable:
+        symbolic_names_ignored: [ ]
+      # OSGi events tracking
+      event_stable:
+        # Topics indicating that instance is not stable
+        topics_unstable:
+          - "org/osgi/framework/ServiceEvent/*"
+          - "org/osgi/framework/FrameworkEvent/*"
+          - "org/osgi/framework/BundleEvent/*"
+        # Ignored service names to handle known issues
+        details_ignored:
+          - "*.*MBean"
+          - "org.osgi.service.component.runtime.ServiceComponentRuntime"
+          - "java.util.ResourceBundle"
+        received_max_age: 5s
+      # Sling Installer tracking
+      installer:
+        # JMX state checking
+        state: true
+        # Pause Installation nodes checking
+        pause: true
+
+    # Managed locally (set up automatically)
+    local:
+      # Current runtime dir (Sling launchpad, JCR repository)
+      unpack_dir: "{{ aem_home_dir }}/var/instance"
+      # Archived runtime dir (AEM backup files '*.aemb.zst')
+      backup_dir: "{{ aem_home_dir }}/var/backup"
+      # Additional tools needed to manage instance
+      tool_dir: "{{ aem_tool_dir }}"
+
+      # Oak Run tool options (offline instance management)
+      oak_run:
+        download_url: "https://repo1.maven.org/maven2/org/apache/jackrabbit/oak-run/1.44.0/oak-run-1.44.0.jar"
+        store_path: "crx-quickstart/repository/segmentstore"
+
+      # Source files
+      quickstart:
+        # AEM SDK ZIP or JAR
+        dist_file: "{{ aem_home_dir }}/lib/{aem-sdk,cq-quickstart}-*.{zip,jar}"
+        # AEM License properties file
+        license_file: "{{ aem_home_dir }}/lib/license.properties"
+
+    # Status discovery (timezone, AEM version, etc)
+    status:
+      timeout: 500ms
+
+    # JCR Repository
+    repo:
+      property_change_ignored:
+        # AEM assigns them automatically
+        - "jcr:created"
+        - "cq:lastModified"
+        # AEM encrypts it right after changing by replication agent setup command
+        - "transportPassword"
+
+    # CRX Package Manager
+    package:
+      # Force re-uploading/installing of snapshot AEM packages (just built / unreleased)
+      snapshot_patterns: [ "**/*-SNAPSHOT.zip" ]
+      # Use checksums to avoid re-deployments when snapshot AEM packages are unchanged
+      snapshot_deploy_skipping: true
+      # Disable following workflow launchers for a package deployment time only
+      toggled_workflows: [ /libs/settings/workflow/launcher/config/asset_processing_on_sdk_*,/libs/settings/workflow/launcher/config/update_asset_*,/libs/settings/workflow/launcher/config/dam_* ]
+
+    # OSGi Framework
+    osgi:
+      shutdown_delay: 3s
+
+      bundle:
+        install:
+          start: true
+          start_level: 20
+          refresh_packages: true
+
+    # Crypto Support
+    crypto:
+      key_bundle_symbolic_name: com.adobe.granite.crypto.file
+
+  java:
+    # Require following versions before e.g running AEM instances
+    version_constraints: ">= 11, < 12"
+
+    # Pre-installed local JDK dir
+    # a) keep it empty to download open source Java automatically for current OS and architecture
+    # b) set it to absolute path or to env var '[[.Env.JAVA_HOME]]' to indicate where closed source Java like Oracle is installed
+    home_dir: ""
+
+    # Auto-installed JDK options
+    download:
+      # Source URL with template vars support
+      url: "https://github.com/adoptium/temurin11-binaries/releases/download/jdk-11.0.18%2B10/OpenJDK11U-jdk_[[.Arch]]_[[.Os]]_hotspot_11.0.18_10.[[.ArchiveExt]]"
+      # Map source URL template vars to be compatible with Adoptium Java
+      replacements:
+        # Var 'Os' (GOOS)
+        "darwin": "mac"
+        # Var 'Arch' (GOARCH)
+        "x86_64": "x64"
+        "amd64": "x64"
+        "386": "x86-32"
+        # enforce non-ARM Java as some AEM features are not working on ARM (e.g Scene7)
+        "arm64": "x64"
+        "aarch64": "x64"
+
+  output:
+    log:
+      # File path of logs written especially when output format is different than 'text'
+      file: "{{ aem_home_dir }}/var/log/aem.log"
+      # Controls where outputs and logs should be written to when format is 'text' (console|file|both|none)
+      mode: both
+
+  base:
+    # Location of temporary files (downloaded AEM packages, etc)
+    tmp_dir: "{{ aem_tmp_dir }}"
+    # Location of supportive tools (downloaded Java, OakRun, unpacked AEM SDK)
+    tool_dir: "{{ aem_tool_dir }}"

examples/local/provision.yml

@@ -0,0 +1,38 @@
+---
+- name: Provision instances
+  hosts: localhost
+  tasks:
+    - name: Enable CRX DE
+      wttech.aem.osgi_config:
+        command: save
+        pid: org.apache.sling.jcr.davex.impl.servlets.SlingDavExServlet
+        props:
+          alias: /crx/server
+
+    - name: Configure replication agent for publishing content
+      wttech.aem.repl_agent:
+        command: setup
+        instance_id: local_author
+        location: author
+        name: publish
+        props:
+          enabled: true
+          transportUri: "{{ aem_publish_http_url }}/bin/receive?sling:authRequestLogin=1"
+          transportUser: "{{ aem_instance_user }}"
+          transportPassword: "{{ aem_instance_password }}"
+          userId: "{{ aem_instance_user }}"
+
+    - name: Configure replication agent for flushing dispatcher cache
+      wttech.aem.repl_agent:
+        command: setup
+        instance_id: local_publish
+        location: publish
+        name: flush
+        props:
+          enabled: true
+          transportUri: "{{ aem_dispatcher_http_url }}/dispatcher/invalidate.cache"
+          protocolHTTPHeaders:
+            - "CQ-Action: {action}"
+            - "CQ-Handle: {path}"
+            - "CQ-Path: {path}"
+            - "Host: publish"

examples/local/run.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env sh
+
+# ===== Configuration =====
+PLAYBOOK=${1:-"start"}
+FLAGS=${2:-"-v"}
+
+# ===== Prerequisites =====
+
+echo ""
+echo "===== Installing AEM Compose CLI ====="
+echo ""
+
+(cd ../../../aemc && make install)
+export AEM_CLI_EXECUTABLE=$(whereis aem | awk -F': ' '{print $2}')
+
+echo ""
+echo "===== Installing AEM Compose Ansible Collection ====="
+echo ""
+
+(cd ../../ && sh install.sh)
+
+# ===== Execution =====
+
+echo ""
+echo "===== Executing AEM Compose Ansible ====="
+echo ""
+echo "Playbook: ${PLAYBOOK}"
+echo ""
+
+ansible-playbook -i "inventory" "${PLAYBOOK}.yml" --connection=local "${FLAGS}"

examples/local/start.yml

@@ -0,0 +1,11 @@
+---
+- name: Start instances
+  hosts: localhost
+  tasks:
+    - name: Create instance(s)
+      wttech.aem.instance:
+        command: create
+
+    - name: Start instance(s)
+      wttech.aem.instance:
+        command: start

examples/local/stop.yml

@@ -0,0 +1,7 @@
+---
+- name: Stop instances
+  hosts: localhost
+  tasks:
+    - name: Stop instances
+      wttech.aem.instance:
+        command: stop