DocumentationAEMAEM TutorialsAEM as a Cloud Service Tutorials

Set up local AEM SDK set-up-local-aem-sdk

Last update: Thu Jan 25 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

CREATED FOR:

  • Beginner
  • Developer

Adobe Experience Manager (AEM) can be run locally using the AEM as a Cloud Service SDK’s Quickstart Jar. This allows developers to deploy to, and test custom code, configuration, and content before committing it to source control, and deploying it to a AEM as a Cloud Service environment.

Note that ~ is used as shorthand for the User’s Directory. In Windows, this is the equivalent of %HOMEPATH%.

Install Java™

Experience Manager is a Java™ application, and thus requires the Oracle Java™ SDK to support the development tooling.

  1. Download and install the latest Java™ SDK 11
  2. Verify that Oracle Java™ 11 SDK is installed by running the command:
macOS
code language-shell 
$ java --version
Windows
code language-shell 
$ java -version
Linux®
code language-shell 
$ java --version

Java

Download the AEM as a Cloud Service SDK

The AEM as a Cloud Service SDK, or AEM SDK, contains the Quickstart Jar used to run AEM Author and Publish locally for development, as well as the compatible version of the Dispatcher Tools.

  1. Log in to https://experience.adobe.com/#/downloads with your Adobe ID
    • Note that your Adobe Organization must be provisioned for AEM as a Cloud Service to download the AEM as a Cloud Service SDK.
  2. Navigate to the AEM as a Cloud Service tab
  3. Sort by Published Date in Descending order
  4. Click on the latest AEM SDK result row
  5. Review and accept the EULA, and tap the Download button

Extract the Quickstart Jar from the AEM SDK zip

  1. Unzip the downloaded aem-sdk-XXX.zip file

Set up local AEM Author service set-up-local-aem-author-service

The local AEM Author Service provides developers with a local experience digital marketers/content authors will share to create and manage content. AEM Author Service is designed both as an authoring and preview environment, allowing most validations of feature development can be performed against it, making it a vital element of the local development process.

  1. Create the folder ~/aem-sdk/author

  2. Copy the Quickstart JAR file to ~/aem-sdk/author and rename it to aem-author-p4502.jar

  3. Start the local AEM Author Service by executing the following from the command line:

    • java -jar aem-author-p4502.jar
      • Provide the admin password as admin. Any admin password is acceptable, however it is recommend to use the default for local development to reduce the need to reconfigure.

    You cannot start the AEM as Cloud Service Quickstart Jar by double-clicking.

  4. Access the local AEM Author Service at http://localhost:4502 in a Web browser

macOS
code language-shell 
$ mkdir -p ~/aem-sdk/author
$ cp aem-sdk-Quickstart-XXX.jar ~/aem-sdk/author/aem-author-p4502.jar
$ cd ~/aem-sdk/author
$ java -jar aem-author-p4502.jar
Windows
code language-shell 
$ mkdir -p c:\Users\<My User>\aem-sdk\author
$ copy aem-sdk-Quickstart-XXX.jar c:\Users\<My User>\aem-sdk\author\aem-author-p4502.jar
$ cd c:\Users\<My User>\aem-sdk\author
$ java -jar aem-author-p4502.jar
Linux®
code language-shell 
$ mkdir -p ~/aem-sdk/author
$ cp aem-sdk-Quickstart-XXX.jar ~/aem-sdk/author/aem-author-p4502.jar
$ cd ~/aem-sdk/author
$ java -jar aem-author-p4502.jar

Set up local AEM Publish service

The local AEM Publish Service provides developers with the local experience end-users of the AEM will have, such as browsing the Web site hosed on AEM. A local AEM Publish Service is important as it integrates with AEM SDK’s Dispatcher tools and allows developers to smoke-test and fine-tune the final end-user facing experience.

  1. Create the folder ~/aem-sdk/publish

  2. Copy the Quickstart JAR file to ~/aem-sdk/publish and rename it to aem-publish-p4503.jar

  3. Start the local AEM Publish Service by executing the following from the command line:

    • java -jar aem-publish-p4503.jar
      • Provide the admin password as admin. Any admin password is acceptable, however it is recommend to use the default for local development to reduce the need to reconfigure.

    You cannot start the AEM as Cloud Service Quickstart Jar by double-clicking.

  4. Access the local AEM Publish Service at http://localhost:4503 in a Web browser

macOS
code language-shell 
$ mkdir -p ~/aem-sdk/publish
$ cp aem-sdk-Quickstart-XXX.jar ~/aem-sdk/publish/aem-publish-p4503.jar
$ cd ~/aem-sdk/publish
$ java -jar aem-publish-p4503.jar
Windows
code language-shell 
$ mkdir -p c:\Users\<My User>\aem-sdk\publish
$ copy aem-sdk-Quickstart-XXX.jar c:\Users\<My User>\aem-sdk\publish\aem-publish-p4503.jar
$ cd c:\Users\<My User>\aem-sdk\publish
$ java -jar aem-publish-p4503.jar
Linux®
code language-shell 
$ mkdir -p ~/aem-sdk/publish
$ cp aem-sdk-Quickstart-XXX.jar ~/aem-sdk/publish/aem-publish-p4503.jar
$ cd ~/aem-sdk/publish
$ java -jar aem-publish-p4503.jar

Set up local AEM services in prerelease mode

The local AEM runtime can be started in prerelease mode allowing a developer to build against the AEM as a Cloud Service’s next release’s features. Prerelease is enabled by passing the -r prerelease argument on the local AEM runtime’s first start. This can be used with both local AEM Author and AEM Publish services.

macOS
code language-shell 
# For AEM Author service in prerelease mode
$ java -jar aem-author-p4502.jar -r prerelease

# For AEM Publish service in prerelease mode
$ java -jar aem-publish-p4503.jar -r prerelease
Windows
code language-shell 
# For AEM Author service in prerelease mode
$ java -jar aem-author-p4502.jar -r prerelease

# For AEM Publish service in prerelease mode
$ java -jar aem-publish-p4503.jar -r prerelease
Linux®
code language-shell 
# For AEM Author service in prerelease mode
$ java -jar aem-author-p4502.jar -r prerelease

# For AEM Publish service in prerelease mode
$ java -jar aem-publish-p4503.jar -r prerelease

Simulate Content Distribution content-distribution

In a true Cloud Service environment content is distributed from the Author Service to the Publish Service using Sling Content Distribution and the Adobe Pipeline. The Adobe Pipeline is an isolated microservice available only in the cloud environment.

During development, it may be desirable to simulate the distribution of content using the local Author and Publish service. This can be achieved by enabling the legacy Replication agents.

NOTE
Replication agents are only available to use in the local Quickstart JAR and provide only a simulation of content distribution.

  1. Login to the Author service and navigate to http://localhost:4502/etc/replication/agents.author.html.

  2. Click Default Agent (publish) to open the default Replication agent.

  3. Click Edit to open the agent’s configuration.

  4. Under the Settings tab, update the following fields:

    • Enabled - check true
    • Agent User Id - Leave this field empty

    Replication Agent Configuration - Settings

  5. Under the Transport tab, update the following fields:

    • URI - http://localhost:4503/bin/receive?sling:authRequestLogin=1
    • User - admin
    • Password - admin

    Replication Agent Configuration - Transport

  6. Click Ok to save the configuration and enable the Default Replication Agent.

  7. You can now make changes to content on the Author service and publish them to the Publish service.

Publish Page

Quickstart Jar start-up modes

The naming of the Quickstart Jar, aem-<tier>_<environment>-p<port number>.jar specifies how it will start up. Once AEM as started in a specific tier, author or publish, it cannot be changed to the alternate tier. To do this, the crx-Quickstart folder generated during the first run must be deleted, and Quickstart Jar must be run again. Environment and Ports can be changed, however they require stop/start of the local AEM instance.

Changing environments, dev, stage and prod, can be useful for developers to ensure environment-specific configurations are correctly defined and resolved by AEM. It is recommended that local development primarily be done against the default dev environment run mode.

The available permutations are as follows:

Quickstart Jar filename
Mode description
aem-author-p4502.jar
As Author in Dev run mode on port 4502
aem-author_dev-p4502.jar
As Author in Dev run mode on port 4502 (same as aem-author-p4502.jar)
aem-author_stage-p4502.jar
As Author in Staging run mode on port 4502
aem-author_prod-p4502.jar
As Author in Production run mode on port 4502
aem-publish-p4503.jar
As Publish in Dev run mode on port 4503
aem-publish_dev-p4503.jar
As Publish in Dev run mode on port 4503 (same as aem-publish-p4503.jar)
aem-publish_stage-p4503.jar
As Publish in Staging run mode on port 4503
aem-publish_prod-p4503.jar
As Publish in Production run mode on port 4503

Note that the port number can be any available port on the local development machine, however by convention:

  • Port 4502 is used for the local AEM Author service
  • Port 4503 is used for the local AEM Publish service

Changing these may require adjustments to AEM SDK configurations

Stopping an local AEM runtime

In order to stop a local AEM runtime, either AEM Author or Publish service, open the command line window that was used to start the the AEM Runtime, and tap Ctrl-C. Wait for AEM to shutdown. When the shutdown process is complete, the command line prompt is available.

Optional local AEM runtime set up tasks

When to update the Quickstart Jar

Update the AEM SDK at least monthly on, or shortly after, the last Thursday of each month, which is the release cadence for AEM as a Cloud Service “feature releases”.

WARNING
Updating the Quickstart Jar to a new version requires replacing the entire local development environment, resulting in a loss of all code, configuration and content in the local AEM repositories. Ensure that any code, config or content that should not be destroyed is safely committed to Git, or exported from the local AEM instance as AEM Packages.

How to avoid content loss when upgrading the AEM SDK

Upgrading the AEM SDK is effectively creating a brand new AEM runtime, including a new repository, meaning any changes made to a prior AEM SDK’s repository are lost. The following are viable strategies for aiding in persisting content between AEM SDK upgrades, and can be used discretely or in concert:

  1. Create a content package dedicated to containing “sample” content to aid in development, and maintain it in Git. Any content that should be persisted through AEM SDK upgrades would be persisted into this package, and re-deployed after upgrading the AEM SDK.
  2. Use oak-upgrade with the includepaths directive, to copy content from the prior AEM SDK repository to the new AEM SDK repository.
  3. Backup any content using AEM Package Manager and content packages on the prior AEM SDK, and re-install them on the new AEM SDK.

Remember, using the above approaches to maintain code between AEM SDK upgrades, indicates a development anti-pattern. Non-disposable code should originate in your Development IDE and flow into AEM SDK via deployments.

Troubleshooting

Double-clicking the Quickstart Jar file results in an error troubleshooting-double-click

When double-clicking the Quickstart Jar to start, an error modal is displayed preventing AEM from starting locally.

Troubleshooting - Double-click the Quickstart Jar file

This is because AEM as a Cloud Service Quickstart Jar does not support double-clicking of the Quickstart Jar to start AEM locally. Instead, you must run the Jar file from that command line.

To start AEM Author service, cd into the directory containing the Quickstart Jar and execute the command:

macOS
code language-shell 
$ java -jar aem-author-p4502.jar
Windows
code language-shell 
$ java -jar aem-author-p4502.jar
Linux®
code language-shell 
$ java -jar aem-author-p4502.jar

or, to start AEM Publish service, cd into the directory containing the Quickstart Jar and execute the command:

macOS
code language-shell 
$ java -jar aem-publish-p4503.jar
Windows
code language-shell 
$ java -jar aem-publish-p4503.jar
Linux®
code language-shell 
$ java -jar aem-publish-p4503.jar

Starting the Quickstart Jar from the command line immediately aborts troubleshooting-java-8

When starting the Quickstart Jar from the command line, the process immediately aborts and the AEM service does not start, with the following error:

➜  ~/aem-sdk/author: java -jar aem-author-p4502.jar
Loading quickstart properties: default
Loading quickstart properties: instance
java.lang.Exception: Quickstart requires a Java Specification 11 VM, but your VM (Java HotSpot(TM) 64-Bit Server VM / Oracle Corporation) reports java.specification.version=1.8
  at com.adobe.granite.quickstart.base.impl.Main.checkEnvironment(Main.java:1046)
  at com.adobe.granite.quickstart.base.impl.Main.<init>(Main.java:646)
  at com.adobe.granite.quickstart.base.impl.Main.main(Main.java:981)
Quickstart: aborting

This is because AEM as a Cloud Service requires Java™ SDK 11 and you are running a different version, most likely Java™ 8. To resolve this issue, download and install Oracle Java™ SDK 11.

Once Oracle Java™ 11 SDK is installed, verify it is the active version by running the command from the command line:

macOS
code language-shell 
$ java --version
Windows
code language-shell 
$ java -version
Linux®
code language-shell 
$ java --version

Additional Resources

recommendation-more-help
4859a77c-7971-4ac9-8f5c-4260823c6f69