Contentful: How to avoid messing up your production content using environments

The problem: I have a .NET web application with a separate test and production environment. My content is stored in Contentful.

Now I have been asked to create a new feature, which involves changing the content model for my content, and I want to try out this new feature in my test environment without messing up the content in the production environment.

The feature in Contentful for keeping different versions of your content and content models is called "environments".

This name is a bit misleading. A Contentful environment has more in common with a feature branch in git than a test environment on your web server. For the rest of this blog post, I will therefore refer to this specifically as "Contentful environment" to avoid confusion.

The Contentful environment used by default for the production environment is called "master". The other environments are branched off from the master Contentful environment and usually deleted after the changes to them have been migrated back to master.

More information on Contentful's website: https://www.contentful.com/developers/docs/concepts/multiple-environments/

Create a new Contentful environment

The first step for working on the new feature, is to create a new Contentful environment. This is simple enough:

1. Navigate to Settings → Environments
2. Click "Add environment"
3. Name your new environment, for example "feature-1" and make sure you clone the environment currently used in production:

Make the new Contentful environment readable

By default, the new environment does not inherit the access rights of the master environment. This means that your application will not have access to read the content stored there.

To fix this, first check which API token is currently in use in appsettings.json.

appsettings.json

{
  "ContentfulOptions": {
    "SpaceId": "abc789",
    "DeliveryApiKey": "xyz123",
  }
}

In the above example, my API key is "xyz123". I can either give this API key access to the newly created feature-1 Contentful environment or create a new access token.

To give the existing token access to feature-1, do the following:

1. Navigate to Settings → API keys
2. Click the name of the existing token
3. At the bottom of the page, check feature-1 and click "Save":

Update appsettings.json to use your new Contentful environment feature-1

Go back to appsettings.json and insert a new option "Environment":

appsettings.json

{
  "ContentfulOptions": {
    "SpaceId": "abc789",
    "DeliveryApiKey": "xyz123",
    "Environment": "feature-1"
  }
}

If you have transformation files for each environment, make sure to update the other appsettings as well. In my case, I want to use the same feature-1 Contentful environment in both development (appsettings.json) and the test environment (appsettings.Test.json), so these two files have identical ContentfulOptions.

Make sure the production environment keeps using the master Contentful environment

By default, the production web application will use the settings defined in appsettings.json. To avoid getting test content in production, specify that the master Contentful environment should be used.

appsettings.Production.json

{
  "ContentfulOptions": {
    "SpaceId": "abc789",
    "DeliveryApiKey": "xyz123",
    "Environment": "master"
  }
}

Summary

To avoid messing up production content during development, use a Contentful environment to create a separate dataset you can play around with.

Remember to give read access to your new Contentful environment before you start working with it, and make sure that your application in production is still targeting the master Contentful environment.