Local Development Environment Set up

Last update: 2024-01-25
  • Created for:
  • Beginner
    Developer

This tutorial walks through setting up a local development environment for Adobe Experience Manager (AEM) using the AEM as a Cloud Service SDK. Included are the development tooling required to develop, build and compile AEM Projects, as well as local run times allowing developers to quickly validate new features locally before deploying them to AEM as a Cloud Service via Adobe Cloud Manager.

 Transcript

In this video, we’ll present a high level overview of a local development environment setup with Adobe Experience Manager.

All right, so we’ve really got three main areas to a local development environment. First of all, we’ve got our AEM project. And this is going to contain all of the custom code, configurations, as well as maybe some sample content. And so this is really what the AEM developers going to be working on. This is the main idea behind setting up a local development environment so that we can create code, add additional code and update the same project. And to test out that code, we’re going to use something called a local AEM runtime. And this is basically local versions of the AEM author and publish services that run on a local computer and we have those, we basically install those locally, so that we can rapidly deploy our code from the AEM project. Now that third part is the local dispatcher runtime. And so this is a local version of Apache HTTP web server that includes the AEM dispatcher on top of it. And we install that locally as well, because there’s going to be dispatcher configuration files that we want to update. That’s also part of the AEM project. And we want to make sure that we’re testing all of our code and configurations through the dispatcher, since that is a critical part of the AEM production environment. All right, so several development tools are needed to be installed in order to support development. So AEM is a Java based application. So on the local machine, Java, and the Java SDK would need to be installed. We’ll be using a git for source control, since Cloud Manager also uses git. The AEM project is actually based on Maven. And the AEM project also has a dependency on Node.js. And then finally, we’ll be using Docker to install the local dispatcher runtime. So in addition to those development tools, most developers will set up an integrated development environment or IDE. And so an IDE as an enhanced text editor, it provides syntax highlighting, code completion, integrated compiling, and a whole lot more to accelerate your code development. And now, so IntelliJ, Visual Studio code and Eclipse are some of the more popular IDEs used with AEM development. And there is some additional setup that can be done so that you can rapidly deploy code from within one of these IDEs to a local AEM runtime.

All right, so now let’s step through kind of a high level local development workflow. So as a local developer, everything really starts with the AEM project. And this project, this is built on Apache Maven, and it’s under get source control. And to make code updates and edit this project, most likely, you’ll be using some sort of integrated development environment, IntelliJ, Visual Studio Code, Eclipse, really whatever is your personal preference. Now, in order to test any of these code updates, you would deploy those code updates to the local AEM runtime, which includes an AEM author and AEM publish instances.

So it’s important, of course, to test out all of the authoring functionality. So any code updates we might have, whether it’s a new component, we might be introducing updates to a dialogue, we want to make sure that everything can be authored and that’s working as expected in the author instance. Now, it’s equally important to test our code updates against a publish instance. Typically a publish instance has different permissions, might have a slightly different set of requirements. So we want to make sure anything that we do, we’re also testing against the publish instance.

Lastly, it’s also important that we test any code changes against the dispatcher. So in an AEM production environment, a dispatcher and an Apache HTTP web server, will always sit in front of the AEM publish environment. And so, this dispatcher layer provides critical caching and security features to the overall AEM environment. So whenever we make any code updates, it’s really important that we test to make sure that they’re working as expected when using the dispatcher. And as part of our AEM project, we also have the ability to add customized dispatcher configuration files. And so in order to test those out, and make sure that those configurations are working accurately, we can actually test them locally first by using the dispatcher runtime. So once we’ve tested out these code updates thoroughly against the AEM author and publisher dispatcher, and everything is working as expected, we’re happy with that code, we as the developer can then push those code updates to a centralized repository in Cloud Manager. And so once those code updates are in Cloud Manager, they can then be promoted to AEM as a cloud service environments using cloud managers CI/CD pipeline. All right, so now we want to look at a local development environment setup in action. And so the first thing that we want to look at is the AEM project itself. So I’ve got that, I’ve got a dedicated folder called Code. And this is where my AEM project is. And I’m just using the finished reference site, the weekend tutorial. This is the finished code base for that tutorial.

So as a developer, if we want to make any updates to the code base, we’d be modifying the folders and files inside this project. Now in order to accelerate our development, we would open up the AEM project inside an integrated development environment or IDE. So in this case, I happen to be using Visual Studio Code.

And so if I’m a developer, and let’s say I wanted to create a new component, I would create my new component using the IDE.

So in this case, under UI apps, I happen to have demo component that I have been working on. It’s actually quite simple. Really, all it does is output a simple text property. But I would write that in the IDE. And then really, the next step is, how am I going to test out this code and test out this component.

And so that’s where the AEM runtime comes into play. So you can see here I’ve got this folder AEM-SDK. And within that, I’ve got a folder for my author instance. And this includes the AEM quickstart, and I’ve renamed this quickstart, so that it runs on port 4502. And it’s going to run in the author mode. And you’ll also notice that I’ve got a folder for publish. And I’ve got that same quickstart jar, but this time, it’s been renamed to run on port 4503. And it’s going to run in the publish mode.

So I’ve started both of these up, let’s go and check it out. So in the browser, I can navigate to localhost 4502. And I can just go ahead and log in as admin. So this is the full AEM authoring experience. And I’ve already gone ahead and deployed the weekend reference site. So we can go into AEM sites, we can navigate to this homepage, we can go ahead and open it.

So within the editor, we can actually go ahead and simulate authoring a component. So if I’m testing out one of my components, I would want to do that in the author environment.

Now if we navigate to localhost 4503, this is going to be the AEM publish instance that we had started. And I’ve also deployed the weekend reference site here. And again, as a developer, if we’re developing a new component, we would want to also test out that code and functionality on the publish instance.

So now if I’m working on my AEM component, I would go into my IDE, and then synchronize this code base with the local AEM instance. And one of the important parts of setting up your IDE, is installing some tools that allow you to quickly synchronize this code with a local running instance of AEM. So I’ll just go ahead and export this component to the local AEM author instance.

And if we return to the AEM author in the browser, refresh the page. Now we can see that demo component. And so we can drag it onto the page. We can configure it, test out the authoring dialogues, test out that everything is rendering correctly. And then yeah, we can continue to iterate on it so we can return back to our IDE, make some code updates, deploy them. And, basically continue to work on the component until it’s working correctly. Now as a best practice, we would also recommend deploying that same code base and testing out the functionality on the publish instance. Just to verify again, that everything is behaving as expected.

All right, so the last area of a local development environment that we want to talk about is the dispatcher runtime.

Now, the dispatcher runtime that’s available to simulate AEM as a cloud service, is actually available as a Docker image. And so to run this, we’ll actually be using Docker desktop.

Now if I navigate to my file system, under my AEM SDK, we already looked at our author and published folders. And now we’ll look at this third folder, the dispatcher folder. So this is going to contain the Docker image that’s actually going to run the Apache HTTP web server, as well as the dispatcher.

So the dispatcher runtime is actually started from the terminal. So I’ll open up a new terminal window. And I’ll navigate into my dispatcher folder, and then into the dispatcher SDK folder.

And now we can start the dispatcher runtime with this command. And we’ve set the dispatcher to run on port 8080. And it’s going to run in front of our published instance on port 4503. And if we return to the browser, navigate to localhost 8080, we can see the weekend reference homepage, and everything looks as expected. And so this is going to look identical to the AEM publish instance, that’s running on 4503. And that’s because the dispatcher is running in front of it.

Now as we navigate to localhost 8080, you can see that all of the requests are going through the dispatcher.

So why is it so important to have a dispatcher running? Right now everything looks the same. Well, it’s important because the dispatcher provides caching features as well as security filters. So it is possible that our code could behave differently when requests are routed through the dispatcher.

Now there are default dispatcher configurations, but it’s possible based on your application that you would need to tweak these and add some of your own custom configurations. This would be done within the AEM project within the dispatcher module.

And then, of course, you can test out these changes to the dispatcher configuration locally using the dispatcher runtime.

All right, so that concludes this video on a local development environment setup to be used when developing for Adobe Experience Manager. Thanks for watching. -

AEM as a Cloud Service Local Development Environment Technology Stack

The local development environment for AEM can be broken up into three logical groups:

  • The AEM Project contains the custom code, configuration and content that is the custom AEM application.
  • The Local AEM Runtime which runs a local version of AEM Author and Publish services locally.
  • The Local Dispatcher Runtime which runs a local version of Apache HTTP Web Server and Dispatcher.

This tutorial walks through how to install and set up the highlighted items in the above diagram, providing a stable local development environment for AEM development.

File System Organization

This tutorial established the location of the AEM as a Cloud Service SDK artifacts and AEM Project code as follows:

  • ~/aem-sdk is a organizational folder containing the various tools provided by the AEM as a Cloud Service SDK
  • ~/aem-sdk/author contains the AEM Author Service
  • ~/aem-sdk/publish contains the AEM Publish Service
  • ~/aem-sdk/dispatcher contains the Dispatcher Tools
  • ~/code/<project name> contains the custom AEM Project source code

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

Development Tools for AEM Projects

The AEM project is the custom code base containing the code, configuration and content that is deployed via Cloud Manager to AEM as a Cloud Service. The baseline project structure is generated via the AEM Project Maven Archetype.

This section of the tutorial shows how to:

  • Install Java
  • Install Node.js (and npm)
  • Install Maven
  • Install Git

Set up Development Tools for AEM Projects

Local AEM Runtime

The AEM as a Cloud Service SDK provides a QuickStart Jar that runs a local version of AEM. The QuickStart Jar can be used to run either the AEM Author Service or AEM Publish Service locally. Note that while the QuickStart Jar provides a local development experience, not all features available in AEM as a Cloud Service are included in the QuickStart Jar.

This section of the tutorial shows how to:

  • Install Java
  • Download the AEM SDK
  • Run the AEM Author Service
  • Run the AEM Publish Service

Set up the Local AEM runtime

Local Dispatcher Runtime

AEM as a Cloud Service SDK’s Dispatcher Tools provides everything required to set up the local Dispatcher runtime. Dispatcher Tools are Docker-based and provides command line tools to transpile Apache HTTP Web Server and Dispatcher configuration files into a compatible formats and deploy them to Dispatcher running in the Docker container.

This section of the tutorial shows how to:

  • Download the AEM SDK
  • Install Dispatcher Tools
  • Run the local Dispatcher runtime

Set up the Local Dispatcher Runtime

On this page