Environments

Jan Cerman

12 minutes

Environments

Environments in Kontent.ai let you create snapshots of your content. These can be snapshots of your production environment or other environments.In non-production environments, you can safely change the content model and the content itself without affecting what your customers see in production.

Explore your path to mastery

Get to know how to set up, sync, and migrate environments.
Migrate your existing project to use Web Spotlight with environments.

Create an environment

Creating an environment means creating a copy of a selected environment, such as Production. You can use the copy for development and testing purposes. You can create as many environments as your subscription plan allows. If you need to make changes to your content models, we recommend using Kontent.ai’s data-ops tool

for code-first content migration.

Should you clone your project or create environments?Although project cloning and environments work similarly, they serve different purposes.

Use environments to prepare changes in a safe space before going into production. Your developers then take care of propagating those changes to production.
Use a new project for independent channels with different models and no shared content. For example, a new standalone mobile app with a different structure and content strategy than your website.

You can create new environments in

Project settings > Environments.

How to create an environment — Make sure to select which user roles to activate in the new environment.

By default, the content item version history is omitted when cloning environments for a faster cloning experience. If you choose to include version history, the new environment will contain up to 50 latest versions for each content item.

What happens when you create an environment?

By default, cloning a new environment means creating an exact copy of the source environment, including:

Content & assets – assets, content items along with their versions, comments and suggestions, and tasks)
Content model – content types, asset type, content type snippets, and taxonomies
Environment settings – collections, languages, preview URLs, roles, spaces, webhooks, and workflows
- Specific Innovation Lab features, such as the smarter search experience and suggest linked items with AI, will be deactivated in the cloned environment.

User access to the new environment depends on their role. When creating an environment, you can choose which users to activate by selecting their roles. Project managers have access to all environments. Webhooks are set as disabled in the new environment to ensure they don't trigger your production apps and services.

What about subscription plan limits?Your subscription plan limits for content items and assets count only for the environment with the largest number of content items and assets. Bandwidth and API calls count for all environments.

Get your environment ID

You use the environment ID to tell Delivery API where to look for content. An environment ID looks like this: 8d20758c-d74c-4f59-ae04-ee928c0816b.

In Kontent.ai, select a project and its environment using the two drop-downs at the top left.
In Environment settings > General, click to copy the Environment ID to your clipboard.

Select an environment in the UI

You can switch among the current project’s environments using the second drop-down at the top.

Switching between environments — Select an environment to work in.

You can also change environments in

Project settings > Environments by clicking Go to environment.

Clone an existing environment

You can clone an existing environment for backup or development and testing purposes. To clone an existing environment in Kontent.ai:

Go to Project settings > Environments
Click of the environment you want to clone.
Select Clone.

Manage changes between environments

Whether you‘re testing content model changes, migrating content, or backing up your environments, there are tools to help you manage them. The data-ops tool

offers the capability to sync, migrate, clean, and back up content within Kontent.ai. Migration toolkit

is another tool you can use to migrate content from external systems to Kontent.ai, as well as within. Explore the dedicated learning path on how you can work with environments using these tools.

Mark a non-production environment as production

To mark a non-production environment as production, go to

Project settings > Environments, and click Mark as production. This approach swaps environments.

The swap approach is suitable for short-lived environments of small projects. However, in general and especially when managing long-lived environments, we recommend using data-ops

to sync, migrate, backup, restore, and clean environments.

If you want to disable your webhooks in the new production environment, unselect Enable webhooks after the swap is done. Otherwise, the webhooks will be enabled. After you mark the non-production environment as your new production environment, the newly marked environment will appear at the top of the list.

What happens when you swap environments?

When you mark a non-production environment as production:

Environment names stay the same. Make sure to rename both the new production environment and the old now non-production environment to avoid confusion after the swap.
Content & assets, content model, and settings of the environments stay the same. This includes all items, assets, content types, snippets, taxonomies, collections, workflows, roles, languages, preview URLs, and webhooks.
- You can choose to have webhooks enabled or disabled after the swap.
Environment ID and API keys stay the same for both environments. Your apps will continue to work without interruption. However, because the environment IDs and API keys are different for each environment, you need to update them in your app after the swap so the app uses the new production environment.
Users and their (in)active status are carried over from the original production environment. Those active in the original production are activated in the new production. Similarly, the inactive users remain inactive.
Users that exist ONLY in the original production environment will NOT appear in the new production environment after the swap.

Avoid environment swap with custom asset domainsA custom asset domain is tied to a specific environment, regardless of whether the environment is marked as production. This means you can’t use a custom asset domain with the environment swap. After each swap, it'd be necessary to set up new HTTPS certificates.

Considerations

When working with environments, here are some key points to consider:

Once items are migrated to the target environment, reverting changes is not straightforward. Plan carefully, as there’s no built-in rollback mechanism.
Avoid syncing or migrating large changes all at once. Smaller, incremental updates are safer and easier to troubleshoot.
Use snapshots and visual diffs to preview changes before any major updates.
Disable webhooks during migration to avoid triggering unintended actions.
The restore process re-imports entities rather than reverting the environment to a previous state.
Backing up environments via data-ops is meant for occasional use rather than ongoing, automated backups.
Restoring from a backup is a manual, complex process typically requiring hands-on involvement and planning.

Environments

Jan Cerman

12 minutes

Environments

Explore your path to mastery

Get to know how to set up, sync, and migrate environments.
Migrate your existing project to use Web Spotlight with environments.

Create an environment

for code-first content migration.

Should you clone your project or create environments?Although project cloning and environments work similarly, they serve different purposes.

Use environments to prepare changes in a safe space before going into production. Your developers then take care of propagating those changes to production.
Use a new project for independent channels with different models and no shared content. For example, a new standalone mobile app with a different structure and content strategy than your website.

You can create new environments in

Project settings > Environments.

What happens when you create an environment?

By default, cloning a new environment means creating an exact copy of the source environment, including:

Content & assets – assets, content items along with their versions, comments and suggestions, and tasks)
Content model – content types, asset type, content type snippets, and taxonomies
Environment settings – collections, languages, preview URLs, roles, spaces, webhooks, and workflows
- Specific Innovation Lab features, such as the smarter search experience and suggest linked items with AI, will be deactivated in the cloned environment.

Get your environment ID

You use the environment ID to tell Delivery API where to look for content. An environment ID looks like this: 8d20758c-d74c-4f59-ae04-ee928c0816b.

In Kontent.ai, select a project and its environment using the two drop-downs at the top left.
In Environment settings > General, click to copy the Environment ID to your clipboard.

Select an environment in the UI

You can switch among the current project’s environments using the second drop-down at the top.

You can also change environments in

Project settings > Environments by clicking Go to environment.

Clone an existing environment

You can clone an existing environment for backup or development and testing purposes. To clone an existing environment in Kontent.ai:

Go to Project settings > Environments
Click of the environment you want to clone.
Select Clone.

Manage changes between environments

Whether you‘re testing content model changes, migrating content, or backing up your environments, there are tools to help you manage them. The data-ops tool

offers the capability to sync, migrate, clean, and back up content within Kontent.ai. Migration toolkit

is another tool you can use to migrate content from external systems to Kontent.ai, as well as within. Explore the dedicated learning path on how you can work with environments using these tools.

Mark a non-production environment as production

To mark a non-production environment as production, go to

Project settings > Environments, and click Mark as production. This approach swaps environments.

The swap approach is suitable for short-lived environments of small projects. However, in general and especially when managing long-lived environments, we recommend using data-ops

to sync, migrate, backup, restore, and clean environments.

What happens when you swap environments?

When you mark a non-production environment as production:

Environment names stay the same. Make sure to rename both the new production environment and the old now non-production environment to avoid confusion after the swap.
Content & assets, content model, and settings of the environments stay the same. This includes all items, assets, content types, snippets, taxonomies, collections, workflows, roles, languages, preview URLs, and webhooks.
- You can choose to have webhooks enabled or disabled after the swap.
Environment ID and API keys stay the same for both environments. Your apps will continue to work without interruption. However, because the environment IDs and API keys are different for each environment, you need to update them in your app after the swap so the app uses the new production environment.
Users and their (in)active status are carried over from the original production environment. Those active in the original production are activated in the new production. Similarly, the inactive users remain inactive.
Users that exist ONLY in the original production environment will NOT appear in the new production environment after the swap.

Considerations

When working with environments, here are some key points to consider:

Once items are migrated to the target environment, reverting changes is not straightforward. Plan carefully, as there’s no built-in rollback mechanism.
Avoid syncing or migrating large changes all at once. Smaller, incremental updates are safer and easier to troubleshoot.
Use snapshots and visual diffs to preview changes before any major updates.
Disable webhooks during migration to avoid triggering unintended actions.
The restore process re-imports entities rather than reverting the environment to a previous state.
Backing up environments via data-ops is meant for occasional use rather than ongoing, automated backups.
Restoring from a backup is a manual, complex process typically requiring hands-on involvement and planning.