Set up local AEM Runtime
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 prior to 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% .
This video shows how to install and run a local instance of Adobe Experience Manager in just a few minutes with the AEM SDK's local quickstart. This video shows starting the AEM SDK's local quickstart by double-clicking on the quickstart Jar file, however this will not work in Java 8 is installed on the computer. Alternatively, the AEM SDK's local quickstart can be started from the command line using the java -jar ... command as described on this page .
Experience Manager is a Java application, and thus requires the Java SDK to support the development tooling.
- Verify Java 11 SDK is installed by running the command:
- Windows: java -version
- macOS / Linux: java --version
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.
- 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.
- Navigate to the AEM as a Cloud Service tab
- Sort by Published Date in Descending order
- Click on the latest AEM SDK result row
- Review and accept the EULA, and tap the Download button
Extract the Quickstart Jar from the AEM SDK zip
- Unzip the downloaded aem-sdk-XXX.zip file
- Ensure your Experience Manager developer license.properties file is available
Note the same Quickstart Jar and license.properties files are used to start both AEM Author and Publish Services.
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.
- Create the folder ~/aem-sdk/publish
- Copy the Quickstart JAR file to ~/aem-sdk/publish and rename it to aem-publish-p4503.jar
- Copy the license.properties file to ~/aem-sdk/publish
- Start the local AEM Publish Service by executing the following from the command line:
You cannot start the AEM as Cloud Service Quickstart Jar by double-clicking .
- java -jar aem-publish-p4503.jar
- Provide the admin password as admin . Any admin password is acceptable, however its recommend to use the default for local development to reduce the need to re-configure.
- Access the local AEM Publish Service at http://localhost:4503 in a Web browser
$ 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 $ copy ../license.properties c:\Users\<My User>\aem-sdk\publish $ cd c:\Users\<My User>\aem-sdk\publish $ java -jar aem-publish-p4503.jar
macOS / Linux:
$ mkdir -p ~/aem-sdk/publish $ cp aem-sdk-Quickstart-XXX.jar ~/aem-sdk/publish/aem-publish-p4503.jar $ cp ../license.properties ~/aem-sdk/publish $ cd ~/aem-sdk/publish $ java -jar aem-publish-p4503.jar
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:
- As Author in Dev run mode on port 4502
- As Author in Dev run mode on port 4502 (same as aem-author-p4502.jar )
- As Author in Staging run mode on port 4502
- As Author in Production run mode on port 4502
- As Author in Dev run mode on port 4503
- As Author in Dev run mode on port 4503 (same as aem-publish-p4503.jar )
- As Author in Staging run mode on port 4503
- As Author 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 will be available.
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".
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:
- 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.
- Use oak-upgrade with the includepaths directive, to copy content from the prior AEM SDK repository to the new AEM SDK repository.
- 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.
Double-clicking the Quickstart Jar file results in an error
When double-clicking the Quickstart Jar to start, an error modal is displayed preventing AEM from starting locally.
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:
$ java -jar aem-author-p4502.jar
or, to start AEM Publish service, cd into the directory containing the Quickstart Jar and execute the command:
$ java -jar aem-author-p4503.jar
Starting the Quickstart Jar from the command line immediately aborts
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
The 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 Java SDK 11 has been installed, verify it is the active version by executing the following from the command line.
Once Java 11 SDK is installed, verify it is the active version by running the command from the command line:
- Windows: java -version
- macOS / Linux: java --version