Space environments are entities within a space that allow you to create and maintain multiple versions of the space-specific data, and make changes to them in isolation.
By default, every space has one environment, called master. Additionally, multiple sandbox environments can be created. Sandbox environments start out as exact copies of the master environment. Environments are made up of the content model, content, and media. Additionally, locales and UI extensions can be altered per environment. When making changes to any of the aforementioned entities in any environment, including master, the data in all other environments isn’t affected and stays the same.
API keys are bound to a single space. However, they can be configured to only grant access to specific environments. The same applies to webhooks—they can be filtered to trigger only on changes within specific environments.
Please note that for security reasons, any request to an environment using an API key that is not enabled for that environment will return a 404 HTTP status.
Master and sandbox environments usage
Master environment is used as a production environment to deliver content to the end users. Sandbox environments are used for non-production development and testing.
When working with master environment and sandbox environments, consider their technical limitations as follows:
- Master environment and master alias can’t be deleted and their names can’t be changed.
- Our SLAs only cover the availability of content within the master environment of space.
- Sandbox environments don't support entry versioning and CMA snapshots.
Access to environments
Permissions to manage master and sandbox environments and the data they contain is defined by a user's role on the level of space. By default, a user's space role has access only to the master environment. For this default role, it appears as any of the entities and settings listed above are direct children of the space. The Administrator role has access to all environments within a space and can create, read, update, and delete sandbox environments. You can enable a custom role to access specific environments of your choice. Also, you can allow a custom role to manage and use all environments in a space. With this option, content and media rules will apply only in master environment, and not in sandbox environments.
Space environments in the web app
Depending on the role of a user, environments can be managed and the data they contain can be viewed and altered in the web app.
Common uses for space environments
Once your project is up and running, you’ll likely still iterate on it, extend it, and ship improvements. If this is the case, using space environments can supplement your local development. You can create a new environment based on the current state of master and hook up an instance of your application that’s running locally. Then you’ll be ready to make changes to your data and settings.
Editors should edit content in the master environment, while developers can develop new features in a sandbox environment.
Applying changes from sandbox environments to master
Developers can write scripts in the Contentful Migration DSL so that migrations are reproducible. After testing the execution of those scripts in sandbox environments using the Contentful CLI, you can execute those already-tested migration scripts on master to apply the same changes. Learn how to write migrations scripts by reading this tutorial.
Staging / QA
With space environments, it is possible to set up environments and keep them running alongside the master. An example of this can be for staging and QA. If you create staging or QA environments, these aren’t intended to be used for development—but rather as checkpoints. These can be used before applying changes to the master environment or deploying to your production environment.
Similar to our local development example, developers can work on a development environment that’s created directly from master. Once they’ve finished, the changes are applied to the QA environment. This allows QA engineers to perform manual and automated tests on those changes. If the tests pass successfully, the changes are then applied to staging, allowing for final testing in an environment that mimics production.
In an environment that 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 is deleted.
Space environments enable continuous integration by allowing you to create a template space. This template space 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.
Read our documentation on continous integration and deployment pipelines to better understand these workflows.
Since space environments is a feature built mainly for developers, we recommend not to use it to cover editorial workflows. As described above, changes made in the web app cannot be applied back to master, therefore elaborate workaround would have to be implemented to mimic an experience editors are used to.
- Understand the domain model of Contentful
- Read the Space Environments API Documentation
- Learn how to integrate migration scripts and environments into your continuous integration & deployment pipelines
- See how you can evolve your environments programmatically Not what you’re looking for? Try our FAQ.