Skip navigation

Manage environments

Environments in Kentico Kontent let developers create snapshots of your production project. Within the environments, you can safely make changes to the existing content model and the content itself without affecting production. Content and assets within non-production environments do not count towards your subscription plan limit.

Table of contents

    Why use environments?

    Environments provide a way to safely test things in isolation. Ever needed to change something in production? If it's a small thing like fixing a typo or adding a limitation to your types, it's often a non-breaking change. As such it doesn't affect the apps connected to your project. But if you need to make a breaking change in production (for example, change an element's type, adjust the existing content model, or programmatically add structure to hundreds of items), we recommend using a separate sandbox environment to prepare for it.

    Continuous integration with environments

    With environments, you can easily iterate on your Kontent project and continuously improve your app. For example, let's say you want to change the way images are used in your project and want to move towards assets in content components. In situations like these, you start by creating an environment, which becomes a snapshot of your production project. This way you can develop against production data while keeping it intact.

    You connect your environment to your locally running app and start making changes in both the app and the environment. Then verify how your app handles the changes. If everything works correctly, you prepare a migration from the new environment to Production environment. You can first run the migration against yet another environment to ensure it does what you want.

    Once you're done and the production is updated, you remove the environments. You can also use this approach when developing integrations that rely on webhooks or Management API. Each environment has its own set of API keys and can fire its own webhooks.

    Manage environments

    Every Kontent project comes with a default master environment called Production. This environment cannot be deleted nor renamed. You can create as many environments as your subscription plan allows. If you need to synchronize changes between environments, we recommend a code-first migration.

    Environments and their usage

    Environments are a tool for development purposes, not content production. This means that only users with the Manage environments permission can use and manage environments. For producing content and preview, use the Production environment.

    Your subscription plan limits for content items and assets count only for the Production environment. Bandwidth and API calls count for all environments.

    Creating environments

    When you create an environment, it's always based on an existing environment such as Production. The new environment will be a copy of the source environment. All your items, assets, types, snippets, taxonomies, collections, roles, workflow, and languages will be in the new environment as well. Webhooks and preview URLs will not be in the new environment.

    To create a new environment, go to Project settings > Environments and click Create new environment. You can also clone an environment by clicking > Clone.

    Creating an environment for a Kontent project

    Switching between environments

    For projects with multiple environments, you'll see a drop-down list that lets you quickly switch between your environments for the selected project.

    Switching between environments

    Migrating changes between environments

    Changes made in one environment are not synchronized to other environments out-of-the-box. To migrate changes from one environment to another, you need to write migration scripts. This code-first approach is similar to handling database migrations where you create a copy of the database and run your script against the copy before running it against the original.

    With Kontent environments, we recommend using the Kontent CLI toolOpens in a new window to run a series of migrations scripts against a specific environment.

    Example migration

    Imagine you have articles in your project. Each article has its author typed in as "Jane Doe" in a text element. You want to extend this information so that it can contain the author's photo and a short bio. Because it would be tedious to add these details to each article one by one, you create a new content type called Author and reference authors from articles.

    Here's one of the ways to do it: 

    1. Create a new environment and a new branch for your app code.
    2. Develop and run a migration script to add data to the new environment.
      1. Create the Author content type.
      2. Add a linked items element in the Article content type so that you can reference authors.
      3. Migrate existing data – for each author, create a content item and provide just its name.
    3. Test your app code against the new data model.
      • At this point, your app is still backward-compatible.
    4. Run the migration script to add data to the Production environment.
      • Once done, your content creators fill in the names, bio, and photos for each Author item.
    5. Deploy the new version of your application.
    6. Develop and run a migration to remove the original Author text element, which is no longer needed.
      1. Verify the content removal script works correctly against a testing environment.
      2. Run against the Production environment.

    We recommend you check out the Kontent Migrations BoilerplateOpens in a new window. The boilerplate contains sample migration scriptsOpens in a new window you can use to write your own.

    What's next?

    Should you clone your project or create environments?

    Although project cloning and environments work similarly, they serve a different purpose.

    • Use environments to prepare changes for your production project in a safe place. Your developers then take care of propagating those changes to the production project.
    • Use project cloning to create new standalone projects for content production. For example, if you want to run projects based on a similar content model but with slightly different content.