One codebase, many sites

If you have many similar sites that mostly look and behave the same, but have different content, you may want to share code across multiple sites. In the past, the best way to do this was to create multiple GitHub repositories, keep them somehow in sync, and run each site off a dedicated GitHub repository.

AEM supports running multiple sites from the same codebase without having to take care of code replication. This ability is also known as "repoless", because all but your first site don't need a GitHub repository of their own.

Follow this document to learn how to create and manage multiple sites off the same codebase. Make sure you have followed the developer tutorial, as it provides the basics of creating a site on AEM.

How this works

Repoless sites are enabled by the Configuration Service in Adobe Experience Manager, which introduces a couple of concepts such as Organization, Profile, Repository, Site, and Content Source. The following diagram shows how the pieces fit together.

https://main--helix-website--adobe.aem.page/docs/architecture-repoless.svg

Organization

Each site in Adobe Experience Manager belongs to an organization. This organization has the same name as an org on github.com, so that there is no naming conflict. An organization can have multiple sites, profiles, and users.

Profile

Profiles are a way to group and re-use important configurations such as headers, indexes, additional metadata, and so on. A profile can be used by multiple sites within an organization, so that there is consistency among them.

GitHub Repository

For each codebase in Adobe Experience Manager, there is one GitHub repository. By creating a first site that uses this repository through AEM Code Sync, this code will be made available to Adobe Experience Manager and can then be used by multiple sites. When updates are pushed to the GitHub repository, they apply to all sites that use this codebase.

Site

A site combines content, code, and configuration to create a new web experience. Configuration can be attached directly to the site, or it can be referenced from a profile. While a profile can be used by multiple sites, each site can have only one profile. When there is a conflict between the configuration settings in a site and in a profile, the site configuration wins.

Which content source and which codebase to use for a site are configuration settings, too. This enables the re-use of code and repoless sites.

Content Source

The content that makes up a site is pulled from a content source when authors preview or publish content. Typical sources include Microsoft Sharepoint and Google Drive, or the bring-your-own-markup adapter.

Create your first base site

The first step to creating a bunch of sites is to create a first site. This site can be used to serve content, but the most important job is to ensure that code is synchronized from your GitHub repository to all sites that use this codebase.

Pre-requisites

• Github Repository : https://github.com/{org}/{site}
• Content Repository (Gdrive / Sharepoint) : https://{org}.sharepoint.com/sites/aem/Shared%20Documents/{site}

Create organization

• Using the Admin API, we need to create the organization
• Confirm the organization is created and you have administrator privileges.

curl -X GET https://admin.hlx.page/config/{org}.json

Note : Please contact Adobe to obtain administrative privileges to create the organization config

Create site within organization

• Using the Admin API, we create the first site

curl -X POST https://admin.hlx.page/config/{org}/sites/{site}.json \
  -H 'content-type: application/json' \
  --data '{
  "code": {
    "owner": "{org}",
    "repo": "{site}"
  },
  "content": {
    "source": {
      "url": "https://{org}.sharepoint.com/sites/aem/Shared%20Documents/{site}"
    }
  }
}'

The new site is now available at https://main--{site}--{org}.aem.page. Most likely only the 404.html is shown, as no content has been previewed yet.

Create a repoless site

Pre-requisites

• Base site configured with code and content repository using the Admin API (see previous section)
• Content Repository (Gdrive / Sharepoint) for new repoless site : https://{org}.sharepoint.com/sites/aem/Shared%20Documents/{site2}

Create your first repoless site

• Using the Admin API, we create new configuration for the first repoless site

curl -X POST https://admin.hlx.page/config/{org}/sites/{site2}.json \
  -H 'content-type: application/json' \
  --data '{
  "code": {
    "owner": "{org}",
    "repo": "{site}"
  },
  "content": {
    "source": {
      "url": "https://{org}.sharepoint.com/sites/aem/Shared%20Documents/{site2}"
    }
  }
}'

The new site is now available at https://main--{site2}--{org}.aem.page. Most likely only the 404.html is shown, as no content has been previewed.

Now we have created multiple sites sharing the same code base but different content repositories.

Additionally, you can use the Admin API to set other available advanced options to use within configuration management.

What’s not needed once you go repoless

When you start with Adobe Experience Manager, many settings are kept either with your content in the content source, or in the GitHub repository next to your code. With the Configuration Service there is now a central place for these kinds of settings.

Below gives you a comparison between how different areas are configured when we use the document mode (the traditional, distributed configuration) vs. using the Configuration Service API.