Setting up the configuration service

The Configuration Service is used to aggregate and deliver configuration for various consumers in the AEM architecture including: Client, Delivery, HTML Pipeline, and Admin Service.

Configurations stored in the client scope can be consumed from your site or the AEM Sidekick and control functionality and behavior for visitors and authors. All other configurations are internal to the AEM infrastructure and cannot be accessed directly.

The configuration is managed using REST calls to the Admin service (admin.hlx.page). See AEM Admin API for details of the API.

For existing AEM projects (coming from hlx.live) projects, the configuration service aggregates a valid configuration based on the various sources (fstab.yaml, .helix/config.xlsx, etc). This ensures backward compatibility, but means that some features are not available in this document mode (the traditional, distributed configuration).

One of the new features that the configuration service can support is independent code and content definitions per site. A site is a combination of an org name and a site name. This is similar to the GitHub owner and repo tuple, but has no longer a relation to the GitHub project.

For example, a site named website of the org acme could have a code repository adobe/helix-website. The preview URL follows the same scheme, but using site and org instead. In this example: https://main--website--acme.aem.page. (also notice the new 2nd level domain name, aem).

With this new mechanism, it is now possible to have multiple sites that use different content, but use the same code repository. This feature is also known as “repoless”.

Prerequisites

There are some rules and constraints when creating new setups that use the configuration service

  1. Any aem.live organization needs also to exist as github.com org and at least one repository needs to be synced to the Code Bus using AEM Code Sync. This ensures that the organization namespace is properly claimed by an entity that can also claim an org on github.com.
  2. For projects that want to use multiple sites with the same code repository (repoless), there must be one canonical site for which the organization/site matches the github owner/repo. This is required for proper code-config association and CDN push invalidation.

Configuration Example

In this example we will create two new sites, website and products of the acme org, which will both share the same github repository: acme/website. The content is managed in sharepoint, at a fictitious https://acme.sharepoint.com/sites/aem/Shared%20Documents/website and .../products.

We assume that the acme org is already set up and a user was defined that can manage the site configurations.

1. Create new configuration for the first site

Make sure that you are properly authenticated, then using the Admin API, we create the first site:

curl -X POST https://admin.hlx.page/config/acme/sites/website.json \
  -H 'content-type: application/json' \
  -H 'x-auth-token: <your-auth-token>' \
  --data '{
  "code": {
    "owner": "acme",
    "repo": "website"
  },
  "content": {
    "source": {
      "url": "https://acme.sharepoint.com/sites/aem/Shared%20Documents/website"
    }
  }
}'


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

2. Create new configuration for the second site

Using the Admin API, we create the second site:

curl -X POST https://admin.hlx.page/config/acme/sites/products.json \
  -H 'content-type: application/json' \
  -H 'x-auth-token: <your-auth-token>' \
  --data '{
  "code": {
    "owner": "acme",
    "repo": "website"
  },
  "content": {
    "source": {
      "url": "https://acme.sharepoint.com/sites/aem/Shared%20Documents/products"
    }
  }
}'


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

Updating a site's configuration

You can update the site configuration either as a whole document, or only certain sub-structures. For example, to give user bob configuration-admin rights:

curl -X POST https://admin.hlx.page/config/acme/sites/website/access/admin.json \
  -H 'content-type: application/json' \
  -H 'x-auth-token: <your-auth-token>' \
  --data '{
  "role": {
    "config": [
      "bob@acme.org",
    ]
  }
}'

Other examples

Update Code Location

curl -X POST https://admin.hlx.page/config/acme/sites/website/code.json \
  -H 'content-type: application/json' \
  -H 'x-auth-token: <your-auth-token>' \
  --data '{
	"owner": "acme",
	"repo": "boilerplate"
}'

Update Production CDN

curl -X POST https://admin.hlx.page/config/acme/sites/website/cdn/prod.json \
  -H 'content-type: application/json' \
  -H 'x-auth-token: <your-auth-token>' \
  --data '{
		"host": "{host}",
		"type": "fastly",
		"serviceId": "{serviceId}",
		"authToken": "{authToken}"
}'

Update Headers

curl -X POST https://admin.hlx.page/config/acme/sites/website/headers.json \
  -H 'content-type: application/json' \
  -H 'x-auth-token: <your-auth-token>' \
  --data '{
	"/**": [
      {
        "key": "access-control-allow-origin",
        "value": "*"
      }
    ]
}'

Update Folders

Use this for updating the folder mappings.

curl -X POST https://admin.hlx.page/config/acme/sites/website/folders.json \
  -H 'content-type: application/json' \
  -H 'x-auth-token: <your-auth-token>' \
  --data '{
"/products/": "/products/default",
}'

Update Public Custom Configuration

curl -X POST https://admin.hlx.page/config/acme/sites/website/public.json \
  -H 'content-type: application/json' \
  -H 'x-auth-token: <your-auth-token>' \
  --data '{
	"custom": {
		"attribute": "value"
	}
}'

The public configuration can also be accessed via the site host https://main--website--acme.aem.page/config.json.

Update Sidekick Configuration

curl -X POST https://admin.hlx.page/config/acme/sites/website/sidekick.json \
  -H 'content-type: application/json' \
  -H 'x-auth-token: <your-auth-token>' \
  --data '{
    "plugins": [{
      "id": "foo",
      "title": "Foo",
      "url": "https://www.aem.live/"
    }]
  }'

Update robots.txt

curl -X POST https://admin.hlx.page/config/acme/sites/website/robots.txt \
  -H 'content-type: text/plain' \
  -H 'x-auth-token: <your-auth-token>' \
  --data 'User-agent: *
Disallow: /'
style
content

Remove unused configuration files

Once you have enabled the configuration service, the configuration settings there override the settings you have in configuration files in your GitHub repository and your content source, so it is best to remove them:

First remove the files from github:

And after those are removed, check if the hlx.page preview page returns a 404. This means that the internal configuration of the repository based config is cleaned up. Then you can also unpreview and delete the configuration in /.helix folder in your content: