Local Development with AEM and Universal Editor

Are you an AEM developer looking to create a complete local development environment, including the Universal Editor? Look no further! This guide will walk you through setting up a fully local development environment for AEM with the Universal Editor, allowing you to make and test changes without pushing to GitHub.

A Comprehensive Guide for Mac Users

Introduction

Having a robust local development environment is crucial. This is especially true when working with Adobe Experience Manager (AEM) and the new Universal Editor. But let's face it: setting up a local environment that mirrors your production setup can be challenging.

Are you tired of pushing every minor change to GitHub just to see how it looks in the Universal Editor? Do you wish you could test your AEM components locally before committing them? You're not alone, and that's precisely why I have created this guide.

This blog post will walk you through setting up a local development environment for AEM with the Universal Editor. We aim to empower you to make and test changes without pushing to GitHub, allowing faster iteration and more efficient development.

We'll cover everything from setting up a local AEMaaCS instance and configuring the Universal Editor Service to instrumenting your pages for local editing. And because we know that most AEM developers use Macs (let's be honest, they're great for development!), we'll provide Mac-specific scripts to streamline the setup and running processes.

Here's what we'll cover:

The steps needed to set up your local environment
Configuring AEM, the Universal Editor, and Helix CLI
Handling certificates and HTTPS
Instrumenting your pages for local editing
Mac-specific scripts to automate setup and running

By the end of this guide, you'll have a fully functional local AEM development environment with the Universal Editor at your fingertips. So, grab your favourite beverage, fire up your Mac, and let's dive in!

Prerequisites

AEM as a Cloud Service (AEMaaCS) SDK
Node.js (version 20 or later)
OpenSSL
Helix CLI

Step 1: Set Up the Local AEMaaCS Instance

Download and install the AEMaaCS SDK.

Deploy your site content and context-aware configuration to the local instance.

Configure AEM to run on HTTPS using the SSL Configuration Wizard:

a. Navigate to AEM Author > Tools > Security > SSL Configuration.

b. In the Store Credentials step:

Enter and confirm a password for the Key Store associated with the SSL-service system user.
Enter and confirm a password for the global Trust Store.

c. In the Key & Certificate step:

Upload the Private Key in DER format.
Upload the associated SSL Certificate in .crt format.

d. In the SSL Connector step:

Verify or update the HTTPS Hostname (should match the Common Name from the certificate).
Verify or update the HTTPS Port.

e. Verify the SSL setup by clicking "Go to HTTPS URL".

Creating a Self-Signed Certificate for AEM

For development purposes, you can create a self-signed certificate using OpenSSL:

# Create Private Key

openssl genrsa -aes256 -out localhostprivate.key 4096

# Generate Certificate Signing Request using private key

openssl req -sha256 -new -key localhostprivate.key -out localhost.csr -subj '/CN=localhost'

# Generate the SSL certificate and sign with the private key (expires in one year)

openssl x509 -req -extfile <(printf "subjectAltName=DNS:localhost") -days 365 -in localhost.csr -signkey localhostprivate.key -out localhost.crt

# Convert Private Key to DER format

openssl pkcs8 -topk8 -inform PEM -outform DER -in localhostprivate.key -out localhostprivate.der -nocrypt

Use the resulting localhostprivate.der and localhost.crt files in the SSL Configuration Wizard.

Step 2: Set Up Local Universal Editor Service

Download the universal-editor-service.cjs file from Software Distribution.

Generate a certificate for the Universal Editor Service:

openssl req -newkey rsa:2048 -nodes -keyout key.pem -x509 -days 365 -out certificate.pem

Create a .env file with the following content:

UES_PORT=8000

UES_PRIVATE_KEY=./key.pem

UES_CERT=./certificate.pem

UES_TLS_REJECT_UNAUTHORIZED=false

Start the Universal Editor Service:

node ./universal-editor-service.cjs

Step 3: Configure Helix CLI for HTTPS

Update your Helix CLI configuration to run with HTTPS when using aem up.

Step 4: Configure Universal Editor to Load Local Resources

Open CRXDE Lite in your local AEM instance.
Navigate to /conf/global/settings/wcm/franklin/repository.
Set the url property to https://localhost:3000/.

Step 5: Configure AEM to Load Local Resources

The configuration from Step 4 will also apply to AEM, ensuring it loads component-models.json and other resources from localhost.

Step 6: Trust Self-Signed Certificates

Add the self-signed certificates to your browser's trusted certificates.
Add the self-signed certificates to your JVM's truststore.

Step 7: Instrumenting Your Pages

Ensure your pages are instrumented to use the local Universal Editor Service by adding the following meta tag:

Step 8: Starting the Universal Editor

Open your browser and navigate to https://experience.adobe.com/#/aem/editor.
Enter the URL of your local AEM page.

Mac-Specific Scripts for Configuration and Running

For Mac users, we can simplify the setup and running process with some bash scripts. Add these scripts to your project root and make them executable with

chmod +x script_name.sh.

1. Setup Script (setup_local_env.sh)

This script will help you set up the necessary certificates and configuration files.

#!/bin/bash

# setup_local_env.sh

# Create directories

mkdir -p certs

mkdir -p config

# Generate self-signed certificate for AEM

openssl genrsa -aes256 -out certs/localhostprivate.key 4096

openssl req -sha256 -new -key certs/localhostprivate.key -out certs/localhost.csr -subj '/CN=localhost'

openssl x509 -req -extfile <(printf "subjectAltName=DNS:localhost") -days 365 -in certs/localhost.csr -signkey certs/localhostprivate.key -out certs/localhost.crt

openssl pkcs8 -topk8 -inform PEM -outform DER -in certs/localhostprivate.key -out certs/localhostprivate.der -nocrypt

# Generate certificate for Universal Editor Service

openssl req -newkey rsa:2048 -nodes -keyout certs/ues_key.pem -x509 -days 365 -out certs/ues_certificate.pem -subj '/CN=localhost'

# Create .env file for Universal Editor Service

cat << EOF > config/.env

UES_PORT=8000

UES_PRIVATE_KEY=./certs/ues_key.pem

UES_CERT=./certs/ues_certificate.pem

UES_TLS_REJECT_UNAUTHORIZED=false

EOF

echo "Setup complete. Please add the certificates to your system's trust store and JVM trust store."

2. Run Script (run_local_env.sh)

This script will start your local AEM instance, Universal Editor Service, and Helix CLI.

#!/bin/bash

# run_local_env.sh

# Start AEM

echo "Starting AEM..."

./aem-author -r . -p 4502 start

# Start Universal Editor Service

echo "Starting Universal Editor Service..."

node ./universal-editor-service.cjs &

# Start Helix CLI

echo "Starting Helix CLI..."

aem up --https &

echo "Local environment is up and running."

echo "AEM: https://localhost:4502"

echo "Universal Editor Service: https://localhost:8000"

echo "Helix CLI: https://localhost:3000"

Using the Scripts

Place both scripts in your project root directory.

Make them executable:

chmod +x setup_local_env.sh run_local_env.sh

Run the setup script once to configure your environment:

./setup_local_env.sh

Whenever you want to start your local development environment, run:

./run_local_env.sh

Remember to add the generated certificates to your system's trust store and JVM trust store as mentioned in the setup script output.

Troubleshooting

If you encounter 404 errors when editing pages, ensure you use the correct URL for the Universal Editor (https://experience.adobe.com/#/aem/editor).
Double-check that all services run on HTTPS and that you've trusted the self-signed certificates.
If you see a "Your connection is not private" error, this is expected when using self-signed certificates. You can proceed by accepting the risk (for development purposes only).

Conclusion

With this setup, you now have a fully local development environment for AEM with the Universal Editor. You can change your components, content, and configurations without pushing to GitHub, allowing faster iteration and testing.

Regularly sync your local changes with your version control system to ensure your team stays up-to-date with your progress.

Happy developing!

References

Local Dev: https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/developing/universal-editor/local-dev

SSL Wizard: https://experienceleague.adobe.com/en/docs/experience-manager-learn/foundation/security/use-the-ssl-wizard

Thanks for reading

Digital Domain Technologies provides expert Adobe Experience Manager (AEM) consultancy. We have collaborated with some of the world’s leading brands across various AEM platforms, including AEM Cloud, on-premise solutions, Adobe Managed Services, and Edge Delivery Services. Our portfolio includes partnerships with prominent companies such as Twitter (now X), EE, Nissan/Renault Alliance Ford, Jaguar Land Rover, McLaren Sports Cars, Hyundai Genesis, and many others.

/fragments/ddt/proposition

style

bg-dark