Staging & Environments

Separating environments for testing and production is an important practice to ensure high availability of your site, which is why AEM provides each developer with a way to test work on their branch that is separate from the production environment on the main branch.

Many organizations also require in their guidelines the creation of a dedicated staging environment. In this guide we discuss the role of staging environments and best practices for implementing them.

You probably don’t need a staging environment

Each repository running on *.hlx.live has as many testing environments as there are branches. As long as you enable the GitHub branch protection rules require a pull request before merging, require status checks to pass before merging, and require branches to be up to date before merging, each of your feature branches will be up to date with the main branch before it can be merged and will accurately reflect the nature of your published site.

The practice of setting up a staging environment emerged at a time when computing resources were scarce, and an entire development team had to share a single environment to test their changes. This could lead to adverse effects, for instance a breaking bug in one branch could block all other development from progressing.

With dedicated branches for each feature and fix, and a virtually unlimited number of preview environments for these branches, this is no longer an issue and the workaround of a dedicated staging environment is no longer needed.

hlx.page is not a staging environment

In content management, discussions of staging environments are complicated by the fact that authors want to preview their content before being published and developers want to preview their code changes before being merged. With the separation of *.hlx.page for content previews and *.hlx.live for published content, we provide this ability to authors.

In order to make previewing content as fast as possible, *.hlx.page uses different caching rules from *.hlx.live, with one being optimized for immediacy, the other for high cacheability.

This means that *.hlx.page and *.hlx.live behave differently, and consequently *.hlx.page should not be used as a staging environment for code. It is a preview environment for content.

You can preview code in all places

As you sometimes need to preview code that refers to content that has not yet been published, the *.hlx.page environment supports the same branch-based creation of testing environments.

When you should set up a staging environment

For the vast majority of customers, rule 1: “you probably don’t need a staging environment” applies. In case you are applying complex configurations, rewrite rules, or even custom edge code in your content delivery network (CDN), it is highly advisable to set up a staging environment for the CDN.

The following tips apply:

• Use a hostname that follows the pattern of your main website. If your main site is on www.example.com then use stage.example.com as the hostname
• Use your main branch on *.hlx.live as the origin – your intent is to test the CDN, not AEM-specific code which has been tested on the *.hlx.live testing environment. You want to work with real content and accurate caching rules, so use *.hlx.live as the origin
• Flush caches deliberately. Through the built-in CDN integration, publishing content to *.hlx.live and merging code into the main branch will surgically purge the cache to your production CDN. You should ensure that your staging CDN will be purged when appropriate

Setting up a staging CDN is something that is only advised to a small subset of customers. An even smaller subset will have the need to test the interaction between client-side code and CDN configuration.

Following the guideline that there should be as many staging “environments” as there are active branches, it is recommended to set up a staging CDN that mirrors the *.hlx.live URL structure, so that ref.examplestage.com will point to ref–-site--example.hlx.live., allowing each developer to access a dedicated testing environment that combines client-side code and CDN-side configuration in one accessible place.

Following the reasoning above, creating a separate staging branch and mapping this to a separate CDN site is not advisable.