Example: Migration between environments

About migrations

Performing content migrations directly in the production environment poses potential risks. This is why it’s safer to clone the production environment first and perform any modifications there that will undergo experimenting, testing, validation, and then swapping. Any changes, simple or complex, work well with this approach.

Migration scenario

Let's dive into a scenario where you have a project with tourism blog articles. Each article specifies text elements for the country and city, and a rich text element to describe the food, cultural details, and overall experience. Later on, you decide that you'd like to include an exact location to help tourists locate where to go and include public photos taken by other tourists who have been there. This means using custom elements in your blog article content type – one for the map and the other to extract photos based on tourist locations, such as using Instagram hashtags. This is done through embedding or coding. As this is a content model change, it’s ideal to first test this in a cloned non-production environment before committing it to the production environment. Once you assess that this change is tested and validated, you can begin the migration before swapping the environments. Let’s check the scenario step by step.

1. Clone an environment

Make a clone of the production environment to create a safe ground for experimenting and testing your new custom elements. Let’s call this environment Development.  Now, you can make the changes to the content model. In the Development environment, start building and using your custom elements to fetch map locations and images via Instagram and then perform tests.

2. Write scripts for migration

Next, you need to build migration scripts that you can use to modify your content model and the relevant content items. This will enable you to migrate your content model from the current state to the new one.

3. Execute the migration scripts

In your Development environment, execute your migration scripts to update your content model and content items. This ensures a smooth and efficient process while maintaining data integrity.

4. Verify the migration scripts

After confirming that your migration scripts work as desired in the Development environment, it’s essential for you to double-check. Clone your production environment once more to create a Staging environment and execute your migration scripts on this fresh environment. With a fresh Staging environment, you can ensure your scripts work with the latest production content. For example, if someone modified the production content model while you were testing the scripts, you can check whether the migration scripts handle the latest version well. If the migration runs successfully on Staging, you end up with the same content model and content item changes as in the Development environment.

Implement content freeze

This is the stopping point before integrating the migration. Before applying changes to the live environment, we recommend stopping content production in the production environment. You’ll need to coordinate with your content creators to pause all content production so they don’t make any changes during the migration. This step may not be critical, but to ensure a flawless migration, it is recommended.

5. Mark the staging environment as production

When you’re satisfied to see the migration scripts working as intended, you can mark the Staging environment as production. Once you swap the environments, remember to rename the two environments to avoid confusion. Your Staging becomes Live and vice versa. In the diagram below, you can see the two environments undergoing the swap process. The Live environment is being swapped with the Staging environment. The project’s production environment changes from Live to Staging.

6. Clean-up after migration