General concepts > Environments


    Traditional CMSs often treat content as a one-off effort: this makes content management difficult to fit into existing development life cycles.

    Content environments make it easier for your development team to manage and maintain content structure once your content has been published. You can think of environments like code branches: great for testing, development and pre-production environments.

    In short, environments ensure quick turnaround times and flexibility for developers — without interrupting the editorial workflow.

    What's an environment?

    By default, every project has one environment, called primary environment, which is meant to be used for the regular editorial workflow. Additionally, multiple sandbox environments can be created by developers to safely test/experiment new changes in the content.

    Sandbox environments start out as exact copies of one of the existing environments (ie. the primary one). The process of creating a new sandbox starting off from an existing environment is called fork.

    Each environment is identified by a name (ie. master) and stores the following information:

    • Models

    • Records

    • Uploads

    • Plugins

    • The content navigation bar

    • Configuration (locales, timezone settings, appearance, SEO preferences)

    When making changes to any of the aforementioned entities in any environment, including the primary environment, the data in all other environments isn’t affected and stays the same.

    Creating a new sandbox environment

    Inside the Settings > Environments section you can manage all your project's environments. To create a new sandbox starting off from an existing one, just click the Fork button and choose a name for the new environment.

    DatoCMS will perform a deep copy of all the information contained inside the source inside the new sandbox:

    Once there's at least a sandbox environment, developers will be able to switch environments using the top bar panel.

    Editors will never see the this panel thanks to a reduced set of permissions, and will continue their editorial workflow on the primary environment as usual.

    Promotion of sandbox environments

    At any time you can promote a sandbox environment to become the new primary. The old primary environment will be demoted as sandbox environment, and content editors will immediately see the interface refresh. From that moment, they will only be able to see and make changes to the new primary environment:

    To be updated when a sandbox gets renamed, you can setup a webhook listening to the "Environment Promote" event.

    Renaming of environments

    At any time you can change the name of an existing environment. This change won't impact those working on the CMS:

    To be updated when a sandbox gets renamed, you can setup a webhook listening to the "Environment Update" event.

    Force use of sandbox environments

    Changes to the primary environments can be potentially disruptive, so we give you the ability to block any user from editing the primary schema or configuration.

    You can do that by going to Project settings > Global properties and flagging "Force the use of sandbox environments". If enabled, no user can edit the primary environment and make changes to its Schema and Configuration, regardless of its role.