White Lion Docs

Wordpress Headless CMS

Migrating Headless CMS to New Environments

The following observations will hopefully aid you as you create new Headless CMS that mirror production content for staging and development environments.

We will refer to the original WP CMS instance as the source CMS and the new WP CMS instance as the clone CMS for the purpose of this guide.

TIP

The next few steps assume Migrate DB Pro is still unstable and unable to handle the migration of Media & SQL tables due to limited server bandwidth or poor versioning.

Migration Plugins

These plugins will help in the migration process:

  1. Export Media Library
  2. Moving Media Library
  3. Migrate DB Pro v1.9.14
  4. Regenerate Thumbnails

WARNING

These instructions assume you have already hosted a fresh instance of Wordpress either locally or on a review server. For instructions on creating a new WP instance on the review server go here.

Initial Migration of Tables

Using Migrate DB Pro go ahead and pull the source CMS into the clone CMS. Ignore pulling in plugin data in the options menu.

Export Media Library

If you can't ftp or acquire the Media Uploads folder manually follow these steps.

  1. Using the Export Media Library plugin on the source CMSgo toMedia > Export option in the WP-Admin.

Select Folder Structure Nested Folders

Compress Yes

WARNING

Export Media Library is no longer maintained. Although it currently does work with WordPress 5.8 in the WP-Admin window, it can crash your site. Keep this plugin deactivated at all times unless in use. It's recommended to find another way to download Uploads Media Library if possible.

  1. Depending on the where the new clone CMS is being setup you can add the new nested folders directly into the uploads folder or you may need to sftp using Filezilla or Cyberduck to place the contents in the uploads folder.

If you go to Media in the WP-Admin they should appear, however they have no relationship to their original post content and no thumbnails.

Building Relationships

We need to update the SQL database so that the images are correctly identified using the Moving Media Library plugin. This plugin exports the relationships and meta data for the images in JSON format.

  1. Open the Moving Media Library in the source CMS by clicking the tab in the WP-Admin window. Go to Export, follow the instructions, and then download the JSON file.

  2. Open the Moving Media Library plugin on the clone CMS and go to Import.

  3. Under Content for "Before:" add the URL for the source CMS, for "After:" set the URL for the clone CMS. Setting the trailing slash on the URL for both.

  4. Click the checkbox for "Change the URL of the guid at the same time", because we are moving between environments.

  5. Upload the exported JSON from the source CMS.

Now go check Post Types to see the Media Images relationship has been established. You should see them only when you directly click. The thumbnails will still need to be generated.

Regenerating Thumbnails

Open the Regenerating Thumbnails plugin and it should detect all the images. Go ahead and run the plugin.

WARNING

The plugin is unable to generate thumbnails for SVG

You may should be able to inspect your Post Types and see their contents including media images. If they are not showing up there are a few things to try.

Flushing Stale State

This section contains a few observational heuristics, that may help you troubleshoot. Rather than give context to everyone, try them out, test, and then update the documentation. They assume you have followed all previous steps before this correctly. If plugins updates occured as well between the different CMS environments this may help as well.

  • If featured images are not showing up on the post types, try to migrate the source CMS tables again. This helped reconnect the images to their post types.

  • Go to each Post Type > Select One/All > Edit > Update. This actions will help populate/regenerate the clone CMS relationships between images/posts/meta.

  • Update the Settings > Permalinks to help flush the clone CMS db as well.

  • Plugins that were pushed up via github to a staging remote were not being registered properly in their new environment and causing fatal errors. Try SFTP and replacing the plugin folder directly with a fresh version. You may be able to leverage the wp cli for this as well after using SSH to enter server and the root directory project directory.

TIP

You may need to change permission chmod 777 for certain folders in the project directory

"Flush the state, update inputs"

When moving content between environmental databases and CMS it's important to bring awareness to the individual couplings that exist between what's displayed on the screen and the stale state that may exist underneath the hood. Remember to update/refresh the inputs to flush new state into the DB's many coupled references.

Andrew Riefenstahl, 2021, Jamstack for Life

Front End Applications

Gatsby Caveats

If you updated the WPGraphQL in the WP CMS, be sure to update all the Post Types manually as mentioned above in Flush the State sections. The updates may rename fields and cause breaking changes.