Traditional CMSs 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 interupting the editorial workflow.
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
Locales and timezone settings
UI Theme (colors and logo)
Global SEO settings
The content navigation bar
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.
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 pane.
Simple content editors will never see the this panel, and will continue their editorial workflow on the primary environment as usual.
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:
A developer that needs to work safely on a new feature — while other collaborators continue to make changes to the content — should avoid changing models/records directly from the UI, and instead use the following workflow:
Create a new sandbox environment, forking from the primary one;
From now on, exclusively work inside the sandbox;
Write a migration script. This is important: instead of tweaking models/content directly from the UI, write a migration script that uses DatoCMS’s Content Management API to apply the expected changes. This will make the process reproducible, and will enable to run the exact same steps during the final deploy on the most recent version of the primary environment;
Configure your website (or app) to read from the sandbox environment instead of the primary environment, and adapt the code to the new changes the migration script introduced;
If you make any change to the migration script, it’s important to test it again, so simply create a new pristine sandbox environment from the primary environment and re-run the script on it.
To learn more, visit the Write and test migration scripts guide.
Once everything is ready to be shipped in production, the first thing to do is turn on Maintenance mode, so that during the deployment process no one can write new data.
DatoCMS will warn you if other collaborators are currently working on DatoCMS, so you can decide to postpone the deployment or contact the editors:
Once Maintenance mode is activated, follow the following steps:
Create a new sandbox environment forking from the primary env, and re-run the migration script on it.
Deploy a new version of your production website pointing to the new sandbox, and test that everything works as expected;
Promote the sandbox environment to be the new primary. You can keep the old primary environment as a backup.
Turn off Maintenance mode to allow content editors to get back to their regular work on the new primary.
We put no expiration dates on environments, which means that development teams potentially can create multiple restore points.
To learn more, visit the Apply migrations to primary environment guide.
If the team relies heavily on automated testing, environments can be created programmatically and just for the duration of a test. Once it has successfully passed, the environment can be programmatically deleted.
Environments enable continuous integration by allowing you to create a “template environment” to use during tests. This template maintains the exact state you need to run your tests. Because environments are meant to be used as temporary entities for isolation, you don’t need to run any clean-up tasks. Instead, just delete and recreate a new environment for every test.