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 the full API reference.

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 no longer requires a direct relation to the GitHub repository.

For example, a site named website of the org acme could use a code repository acme/boilerplate. The preview URL follows the same scheme, but using site and org instead. In this example: https://main--website--acme.aem.page.

.

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 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. The github.com org can exceptionally be created by Adobe or a trusted implementation partner on the customer’s behalf, but it must have at least one owner from the customer's organization.
  2. For projects that want to use multiple sites with the same code repository (repoless), there must be one canonical site for which the org/site matches the GitHub owner/repo. This is required for proper code-config association and CDN push invalidation.

Create your Organization

Follow the developer tutorial to create your very first site. As part of this process, an aem.live org with the same name as your github.com org will be created, and the github.com user who added the AEM Code Sync App will be added as admin. Contact an Adobe representative if you need a different admin user.

Add your Site

In this example, we create a new site named website under a fictitious acme org.

Note: Before running the example command below:

curl -X PUT https://admin.hlx.page/config/acme/sites/website.json \
  -H 'content-type: application/json' \
  -H 'x-auth-token: {your-auth-token}' \
  --data '{
  "version": 1,
  "code": {
    "owner": "acme",
    "repo": "boilerplate"
  },
  "content": {
    "source": {
      "url": "https://content.da.live/acme/website/",
      "type": "markup"
    }
  }
}'


The resulting site would immediately be available at https://main--website--acme.aem.page. The 404.html would be displayed until content has been previewed.

Updating your Site

You can update the site configuration either as a whole document, or only certain sub-structures. Here are some examples:

Update Access Control

Use this to assign roles to your users. For example, to add user bob to the configuration admin role:

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

Update Code Location

Use this to switch your site to a different codebase (see also repoless):

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

Update Content Location

Use this to switch your site to a different content source (see also repoless):

curl -X POST https://admin.hlx.page/config/{org}/sites/{site}/content.json \
  -H 'content-type: application/json' \
  -H 'x-auth-token: {your-auth-token}' \
  --data '{
    "source": {
      "url": "https://content.da.live/acme/website/",
      "type": "markup"
    }
  }'

Update Production CDN

Use this to configure the CDN settings:

curl -X POST https://admin.hlx.page/config/{org}/sites/{site}/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 Custom Headers

Use this to set custom HTTP headers:

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

Update Public Custom Configuration

Use this to define public project configuration, for example for easy consumption on the client side:

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

Caution: Do not store any secrets in public configuration! It will be accessible to everyone at https://{your-host}/config.json.

Update Sidekick Configuration

Use this to customize the Sidekick:

curl -X POST https://admin.hlx.page/config/{org}/sites/{site}/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 Indexing Configuration

Use this to add your indexing configuration:

curl -X POST https://admin.hlx.page/config/{org}/sites/{site}/content/query.yaml \
  -H 'content-type: text/yaml' \
  -H 'x-auth-token: {your-auth-token}' \
  --data @your-query.yaml

Update Sitemap Configuration

Use this to add your sitemap configuration:

curl -X POST https://admin.hlx.page/config/{org}/sites/{site}/content/sitemap.yaml \
  -H 'content-type: text/yaml' \
  -H 'x-auth-token: {your-auth-token}' \
  --data @your-sitemap.yaml

Update robots.txt

Use this to customize instructions for robots and crawlers:

curl -X POST https://admin.hlx.page/config/{org}/sites/{site}/robots.txt \
  -H 'content-type: text/plain' \
  -H 'x-auth-token: {your-auth-token}' \
  --data 'User-agent: *
Allow: /
Sitemap: https://{your-host}/sitemap.xml'
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: