AEM Multi-Project Example

Description

This project could be used to start developing long-term project based on AEM.

To start developing application/library based on AEM it is recommended to use Gradle AEM Single instead.

Documentation for AEM plugin is available in project Gradle AEM Plugin.

Screenshot

Table of Contents

• Features
• Quickstart
• Environment
• Structure
• Building
• Tips & tricks
• Running tests
• Attaching debugger
• Extending build

Features

Main motivation of this project is to automate all aspects of AEM development and make it a breeze.

Archetyping:

• Generating project from archetype using Gradle Fork Plugin,
• Generating user-specific build properties using friendly GUI

Environment:

• Automatic native local AEM instance(s) setup,
• Automatic HTTPD server with AEM dispatcher setup (based on Docker),
• Hosts file amendment
• Health checking

Back-end:

• Building OSGi bundle ready for AEM sites development

Front-end:

• Setup of popular UI build toolkit: NodeJS, Yarn and Webpack for advanced assets bundling (modular JS, ECMAScript6 transpilation, SCSS compilation with PostCSS, code style checks etc).
• Integrated SCSS compilation on AEM side using AEM Sass Compiler.

Testing:

• Stubbing using AEM Stubs Tool
• Unit tests
• Integration tests using Karate Framework and JSoup.
• Functional tests using Cypress
• Performance tests using Gradle Lighthouse Plugin

Maintenance:

• Automatic AEM migration scripts execution using AEM Easy Content Upgrade,
• Automatic AEM access control configuration applying using Access Control Tool,
• Interactive incident monitoring / logs monitoring with filtering.

Quickstart

1. Fork project using command:

   git clone https://github.com/wttech/gradle-aem-multi.git && cd gradle-aem-multi && sh gradlew fork

   and specify properties:

   

   and wait until project is forked then enter configured target directory.

2. Setup user specific project configuration using command:

   sh gradlew props

   and specify properties:

   

3. Setup local AEM instances with dependencies and AEM dispatcher (see prerequisites) then build application using command:

   sh gradlew environmentHosts
   sh gradlew setup

   and wait till complete AEM environment will be ready to use.

4. Develop continuously application using command:

   sh gradlew

   which is an alias for:

   sh gradlew develop

   or to just deploy AEM application (without running anything else):

   sh gradlew :app:aem:all:packageDeploy

Prerequisites

Tested on:

• Java 1.8, 11
• Gradle 6.7
• Adobe AEM 6.5
• Docker 2.4.0.0

Structure

• app - source code generated from Adobe AEM Archetype 23 and adapted to Gradle / Gradle AEM Plugin,
• env - resources and configuration related with setting up local AEM instances and AEM dispatcher,
• test - integration and functional tests requiring full environment setup.

Environment

Project is configured to have local environment which consists of:

• native AEM instances running on local file system,
• virtualized Apache HTTP Server with AEM Dispatcher module running on Docker (official httpd image).

Assumptions:

• AEM author available at http://localhost:4502
• AEM publish available at http://localhost:4503
• Apache web server with Virtual hosts configured for domains:
  • http://example.com -> which maps to /content/example content root on publish

Building

1. Use command gradlew so that Gradle in version according to project will be downloaded automatically.
2. Deploy application:
   • Full assembly and run all tests
     • sh gradlew <=> sh gradlew :develop
   • Only assembly package:
     • sh gradlew :app:aem:all:packageDeploy
   • Only single package or bundle:
     • sh gradlew :app:aem:core::bundleInstall,
     • sh gradlew :app:aem:ui.apps:packageDeploy,
     • sh gradlew :app:aem:ui.content:packageDeploy.
3. Rebuilding front-end only: sh gradlew :app:aem:ui.frontend:build

Tooling

1. Monitoring errors in logs: sh gradlew instanceTail
2. Synchronizing JCR content from AEM to local file system: sh gradlew :app:aem:ui.content:packageSync
3. Interactively updating HTTPD Virtual-Host & AEM Dispatcher configuration: sh gradlew environmentDev
4. Copying JCR content between AEM instances: sh gradlew instanceRcp -Pinstance.rcp.source=http://user:pass@x.x.x.x:4502 -Pinstance.rcp.target=local-author -Pinstance.rcp.paths=[/content/example,/content/dam/example]

Tips & tricks

• To run some task only for subproject, use project path as a prefix, for instance: sh gradlew :app:aem:ui.content:packageDeploy.
• According to recommendations, Gradle daemon should be:
  • enabled on development environments,
  • disabled on continuous integration environments.
• To see more descriptive errors or want to skip some tasks, see command line documentation.

Running tests

IntelliJ

Certain unit tests may depend on the results of running gradle tasks. One such example is the testing of OSGi Services using OSGi Mocks where in order to run a test, the SCR metadata must be available for a class. Running a test like this in IntelliJ results in errors because the IDE is not aware of the Bundle plugin.

This can be worked around by configuring IntelliJ to delegate test execution to Gradle. In order to set this up, go to Settings > Build, Execution, Deployment > Gradle > Runner and set your IDE to delegate IDE build/run actions to Gradle. Alternatively, you can use a dropdown menu to use a specific runner or to decide on a test-by-test basis.

Attaching debugger

1. Execute build with options -Dorg.gradle.debug=true --no-daemon, it will suspend,
2. Attach debugger on port 5005,
3. Suspension will be released and build should stop at breakpoint.

Extending build

For defining new tasks directly in build see:

• Build Script Basics
• More about Tasks

The easiest way to implement custom plugins and use them in project is a technique related with buildSrc/ directory. For more details please read documentation.