Reusing content across sites with AEM authoring as your content source

By default, AEM is tightly bound to your code repository, which meets the majority of use cases. However you may have multiple sites that differ mostly in their content, but could leverage the same code base.

Rather than creating multiple GitHub repositories and running each site off a dedicated GitHub repository while keeping them in sync, AEM supports running multiple sites from the same codebase.

This simplified setup, which eliminates the need for code replication is also known as “repoless”, because all but your first site don’t need a GitHub repository of their own.

If your project requires the repoless flexibility of code reuse across sites, you can activate the feature.

Regardless of how many sites you want to ultimately create in a repoless fashion, you must create your first site, which serves as your base site. This document explains how to create your first site for repoless use.

Prerequisites

To take advantage of this feature, make sure you have done the following.

Your site is already fully set up by following the document Getting Started – Universal Editor Developer Tutorial.
You are running AEM as a Cloud Service 2024.08 at a minimum.

You will also need to ask Adobe to configure the following items for you. Reach out via your Slack channel or raise a support issue to request Adobe to make these changes:

Ask to activate the aem.live configuration service for your environment and that you are configured as an administrator.
Ask to enable the repoless feature for your program by Adobe.
Ask Adobe to create the org for you.

Activate repoless feature

There are several steps to activate repoless functionality for your project. Please substitute your own site and GitHub org information appropriately.

Retrieve access token
Set up configuration service
Add site configuration and technical account
Update AEM configuration
Authenticate site

This document details each of these steps.

Retrieve access token

You will first need an access token to use the configuration service and configure it for the repoless use case.

Go to https://admin.hlx.page/login and use the login_adobe address to login with the Adobe identity provider.
You will be forwarded to https://admin.hlx.page/profile.
By using your browser’s developer tools, copy the value of the x-auth-token either from the JSON web token cookie that the admin.hlx.page page sets.

Once you have your access token, it can be passed in the header of cURL requests in the following format.

--header 'x-auth-token: <your-token>'

Add path mapping for site configuration and set technical account

You need to create a site configuration and add it to your path mapping.

Create a new page at the root of your site and choose the Configuration template.
- You can leave the configuration empty with only the predefined key and value columns. You only need to create it.
Create a mapping in the public configuration to the site configuration using a cURL command similar to the following.

curl --request POST \
  --url https://admin.hlx.page/config/<your-github-org>/sites/<your-aem-project>/public.json \
  --header 'x-auth-token: <your-token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "paths": {
        "mappings": [
            "/content/<your-site-content>/:/",
            "/content/<your-site-content>/configuration:/.helix/config.json"
   ],
        "includes": [
            "/content/<your-site-content>/"
        ]
    }
}'

Validate that the public configuration has been set and is available with a cURL command similar to the following.
curl 'https://main--<your-aem-project>--<your-github-org>.aem.live/config.json'

Once the site configuration is mapped, you can configure access control by defining your technical account so it has privileges to publish.

Sign into the AEM author instance and go to Tools → Cloud Services → Edge Delivery Services Configuration and select the configuration that was automatically created for your site and tap or click Properties in the tool bar.
In the Edge Delivery Services Configuration window, select the Authentication tab and copy the value for the technical account ID.
- It will look similar to <tech-account-id>@techacct.adobe.com
- The technical account is the same for all sites on a single AEM author environment.
Set the technical account for your repoless configuration with a cURL command similar to the following, using the technical account ID that you copied.
- Adapt the admin block to define the users who should have full administrative access to the site.
  1. It is an array of email addresses.
  2. The wildcard * can be used.
  3. See the document Configuring Authentication for Authors for more information.

curl --request POST \
  --url https://admin.hlx.page/config/<your-github-org>/sites/<your-aem-project>/access.json \
  --header 'Content-Type: application/json' \
  --header 'x-auth-token: <your-token>' \
  --data '{
    "admin": {
        "role": {
            "admin": [
                "<email>@<domain>.<tld>"
            ],
            "config_admin": [
                "<tech-account-id>@techacct.adobe.com"
            ]
        },
        "requireAuth": "auto"
    }
}'

Since you now use the configuration service, you can remove fstab.yaml and paths.json from your Git repository.

NOTE: By using the configuration service and exposing the path mapping via config.json, the path.json file is ignored.

Once AEM is configured for repoless use, you must use the configuration service and provide a valid config.json with the paths mapping.

Update AEM configuration

Now you are ready to make the necessary changes to your Edge Delivery Services in AEM.

Sign into the AEM author instance and go to Tools → Cloud Services → Edge Delivery Services Configuration and select the configuration that was automatically created for your site and tap or click Properties in the tool bar.
In the Edge Delivery Services Configuration window, change project type to aem.live with repoless config setup and tap or click Save & Close.
Return to your site using the Universal Editor and ensure that it still renders properly.
Modify some of your content and re-publish.
Visit your published site at https://main--<your-aem-project>--<your-github-org>.aem.page/ and verify that the changes are properly reflected.

Your project is now set up for repoless use.

Troubleshooting

The most common issue encountered after configuring the repoless use case is that pages in the Universal Editor no longer render or you receive a white page or a generic AEM as a Cloud Service error message. In such cases:

View the source of the rendered page.
- Is there actually something rendered (correct HTML head with scripts.js, aem.js, and editor-related JSON files)?
Check the AEM error.log of the author instance for exceptions.
- The most common issue is the page component fails with 404 errors.
- config.json or paths.json can not be loaded
- component-definition.json etc. can not be loaded