Docs

.gitignore

@@ -42,4 +42,6 @@ dev_overrides.tfrc
 *.cer
 *.der
 
-**/aem/home/
+# Terraform examples
+examples/**/.terraform.lock.hcl
+examples/**/lib/

README.md

@@ -26,7 +26,6 @@ The main purpose of this provider is to enable users to:
 - Seamless integration with Terraform for infrastructure provisioning
 - Based on the powerful [AEM Compose](https://github.com/wttech/aemc) tool
 
-
 ## Requirements
 
 - [Terraform](https://developer.hashicorp.com/terraform/downloads) >= 1.0
@@ -56,9 +55,9 @@ go mod tidy
 
 Then commit the changes to `go.mod` and `go.sum`.
 
-## Using the provider
+## Troubleshooting the provider
 
-Fill this in for each provider
+Before running any Terraform command simply set the environment variable `TF_LOG=INFO` (or ultimately `TF_LOG=DEBUG`) to see detailed logs about progress of the setting up the AEM instances.
 
 ## Developing the Provider
 

examples/aws_ssh/aem.tf

@@ -34,6 +34,7 @@ resource "aem_instance" "single" {
   }
 
   compose {
+    config = file("aem.yml") // use templating here if needed: https://developer.hashicorp.com/terraform/language/functions/templatefile
     create = {
       inline = [
         "mkdir -p '${local.aem_single_compose_dir}/aem/home/lib'",

examples/aws_ssh/aem.yml

@@ -0,0 +1,224 @@
+# AEM instances to work with
+instance:
+
+  # Full details of local or remote instances
+  config:
+    local_author:
+      active: true
+      http_url: http://127.0.0.1:4502
+      user: admin
+      password: admin
+      run_modes: [local]
+      jvm_opts:
+        - -server
+        - -Djava.awt.headless=true
+        - -Djava.io.tmpdir=[[canonicalPath .Path "aem/home/tmp"]]
+        - -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=0.0.0.0:14502
+        - -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: true
+      http_url: http://127.0.0.1:4503
+      user: admin
+      password: admin
+      run_modes: [local]
+      jvm_opts:
+        - -server
+        - -Djava.awt.headless=true
+        - -Djava.io.tmpdir=[[canonicalPath .Path "aem/home/tmp"]]
+        - -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=0.0.0.0:14503
+        - -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
+
+  # HTTP client settings
+  http:
+    timeout: 10m
+    debug: false
+    disable_warn: true
+
+  # State checking
+  check:
+    # Time to wait before first state checking (to avoid false-positives)
+    warmup: 1s
+    # Time to wait for next state checking
+    interval: 6s
+    # 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
+    # Specific endpoints / paths (like login page)
+    path_ready:
+      timeout: 10s
+
+
+  # Managed locally (set up automatically)
+  local:
+    # Current runtime dir (Sling launchpad, JCR repository)
+    unpack_dir: "aem/home/var/instance"
+    # Archived runtime dir (AEM backup files '*.aemb.zst')
+    backup_dir: "aem/home/var/backup"
+
+    # 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/lib/{aem-sdk,cq-quickstart}-*.{zip,jar}'
+      # AEM License properties file
+      license_file: "aem/home/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/update_asset_*,/libs/settings/workflow/launcher/config/dam_*]
+    # Also sub-packages
+    install_recursive: true
+    # Use slower HTML endpoint for deployments but with better troubleshooting
+    install_html:
+      enabled: false
+      # Print HTML directly to console instead of writing to file
+      console: false
+      # Fail on case 'installed with errors'
+      strict: true
+
+  # 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
+
+  # Workflow Manager
+  workflow:
+    launcher:
+      lib_root: /libs/settings/workflow/launcher
+      config_root: /conf/global/settings/workflow/launcher
+      toggle_retry:
+        timeout: 10m
+        delay: 10s
+
+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"
+
+base:
+  # Location of temporary files (downloaded AEM packages, etc)
+  tmp_dir: aem/home/tmp
+  # Location of supportive tools (downloaded Java, OakRun, unpacked AEM SDK)
+  tool_dir: aem/home/opt
+
+log:
+  level: info
+  timestamp_format: "2006-01-02 15:04:05"
+  full_timestamp: true
+
+input:
+  format: yml
+  file: STDIN
+
+output:
+  format: text
+  log:
+    # File path of logs written especially when output format is different than 'text'
+    file: aem/home/var/log/aem.log
+    # Controls where outputs and logs should be written to when format is 'text' (console|file|both)
+    mode: console