Skip navigation

Manage environments

9 min read

Environments in Kontent let you create snapshots of your production project. In non-production environments, you can safely make changes to the content model and the content itself without affecting what your customers see on production.

Table of contents

    Environments and their use

    Environments are a tool for development purposes, not for content production

    For example, if you need to adjust the existing content model or programmatically modify hundreds of items, we recommend using a non-production environment to test the change before making it on production.

    Every Kontent project comes with a default environment called Production. This environment cannot be deleted or renamed.

    For content production and preview purposes, use the Production environment.

    Continuous integration with environments

    Let's say you want to change the way you use images in your project and move towards using assets in components. To do that, you need to create a content type for the components and migrate all the image assets to components of that type.

    As with all changes to the content model, it's best to validate what you're doing before migrating to the production environment:

    1. Create a new environment to have a safe testing space.
    2. Write a series of migration scripts to make the content model changes.
    3. Run these scripts in the testing environment to see how your app handles the changes.
    4. If the scripts do what you want, you can safely run the content model migration on production.

    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 trigger its own webhooks.

    What about subscription plan limits?

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

    Create an environment

    Creating an environment means that you essentially create 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 synchronize changes between environments, we recommend using a code-first migration.

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

    Make sure to select roles of users that should be active in the new environment.

    What happens when you create an environment?

    The new environment will contain all items, assets, types, snippets, taxonomies, collections, workflow, roles, and languages from the source environment.

    The users from the source environment may be activated in the new environment as well. When creating an environment, you'll choose which users to activate by selecting their roles. Users with the Project manager role will get always activated because project managers have access to the whole project.

    Webhooks and preview URLs won't be copied in the new environment. You usually don't want to trigger your production apps when testing.

    Switch environments

    If you have access to one or more environments in a project with multiple environments, you'll see a drop-down list for switching between your environments for the selected project.

    Switching between environments

    Migrate 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 a migration script. This code-first approach is similar to handling database migrations. When you migrate a database, 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 tool to run a migration script against a specific environment.

    Example migration

    Let's say you have a project with blog articles. Each article has an author typed manually as “Jane Doe” into a text element. At some point, you decide you want to include additional information about the authors, such as their bio and profile image.

    It would be tedious to add these details to each article one by one. You instead create a new content type called Author and link content items of the Author type in the articles.

    As this is a change of the content model, you want to first test everything in a separate environment before committing it to production. Here's how to do it:

    1. Create a development environment

    Create a new testing branch of your app code and clone your production environment to set up a development sandbox.

    2. Create migration scripts to adjust your content model

    Write migration scripts. You'll use these scripts in the next steps for changing the content model and for migrating content from the old model to the new one.

    A migration script is a set of instructions using Kontent CLI where you programmatically define changes to the content model you want to do. These scripts are also useful for migrating content from the old content model to the new one.

    We recommend you check out the Kontent Migrations Boilerplate. The boilerplate contains a series of migration scripts for each step of this example migration:

    1. Create a content type for authors.
    2. Add a linked items element to the content type of articles.
    3. Migrate the data – extract names of article authors, create a content item for each name, and link it in its respective articles.
    4. Remove the text element for authors' names that's not needed anymore.

    Why not just one script that handles it all?

    It's a good practice to have one migration script per task. That way you know better where to look when something fails.

    3. Run the migration scripts

    Run the migration scripts to update and migrate your content model and data.

    Safety first!

    Make sure to run the migration scripts against the development environment, not the production one. Each environment has its own set of API keys.

    4. Validate the migration scripts

    When your migration scripts are doing what you want under the development environment, it's time for a double check. Create a new staging environment by cloning the production environment afresh. Then run your migration scripts against the new staging environment.

    Although non-critical, this step allows you to make sure that all is going to end well. The production environment has probably changed while you were writing the migration scripts – it's good to check the scripts work with the latest content from production.

    5. Migrate the changes to production

    Now, if your migration scripts did what you want on the staging environment, run them against the production environment. It's safe to assume they'll do your project no harm. To be 100% sure, you can clone your project first to have a backup. After you run the migration scripts, don't forget to also merge your app code branch to main.

    6. Clean-up

    You're done with the migration and your production content model is updated. All that's left is to clean up. Delete the staging and development environments because they're not needed anymore. You'll create new ones the next time you need to change your content model.

    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.