Migrating from Webhook CMS to Contentful & Netlify

When we first founded Sanctuary, we decided to bet on Webhook CMS. It was a modern, static website infrastructure that allowed us to build and deploy sites to the internet within a matter of hours.

However, as we continued using it, we noticed the maintainers started to disappear from the forums. Support tickets would go unchecked, and occasionally we’d have to DM the creator on Twitter just to get him to reboot a service that had been down for a few days.

The final blow came when Firebase end-of-life’d it’s old Auth API in favor of a new way to do it. The Webhook maintainers decided they’d rather shut down the system than fix it:

(As a side, it would be really interesting to know why Webhook CMS went out of business. From the outside looking it, it seemed like a nice, growing business, and had all of the makings of a really solid hosting system.)

Regardless — we had 14 or so websites on Webhook CMS, and none of our clients could log in. We decided to take that matter into our own hands, and develop a generalized migration infrastructure that would allow us to keep those sites running with few individual changes to their codebase:

sanctuarycomputer/webhook2contentful

We selected Contentful & Netlify, because after being burnt by Webhook CMS, we certainly weren’t betting on any small companies going forward.

The following document should serve as a) reference for Developers wishing to replatform their client to Contentful & Netlify, and b) documentation for Clients who are still getting used to their new Contentful backend.

Part 1: Replatforming (for Developers)

In order to replatform your Webhook CMS site to Contentful & Netlify, you’re going to need the following:

1. A Contentful Space
2. The Space ID (Space Settings -> General Settings)
3. A personal access token (Space Settings -> API Keys -> Content Management Tokens -> Generate personal token)*

4. Your original Webhook CMS codebase, and the .firebase.conf file that is gitignored by default (ideally your code is hosted on Github, this will make deployment a breeze)

5. A Netlify Account

*Note: If you’re replatforming a bunch of sites, you can use the same “Personal Access Token” for each, provided they’re in the same Contentful organization.

Step 1 — Copy webhook2contentful into your Webhook codebase

We toyed with the idea of making this a Node module, but we decided against it, because it’s likely that our migration script doesn’t take into account every Webhook CMS feature (just the ones we used).

For that reason, you’ll simply need clone the webhook2contentful repo, and copy & paste the /contentful folder as /libs/contentful in your Webhook CMS repo.

Step 2 — Link webhook2contentful into your Webhook tooling

We need to intercept a couple of key places in the existing Webhook CMS build tooling to move everything from Firebase over to Contentful.

Add the dev dependencies:

npm install contentful-export contentful-management contentful-migration jsonfile dotenv -D

Make the following change to /libs/generator.js:

Make the following change to /tasks/generatorTasks.js:

Make the following change to /lib/swig_filters.js:

Create a .env file (and add it to you .gitignore, unless you’re crazy):

Step 3 — Run the migration

Now that you’ve added webhook2contentful to your build tooling, you’ll have a new grunt task registered with your Webhook CMS project.

(Don’t worry — it’s immutable & non-destructive!)

Simply run:

grunt migrateToContentful

… and hit Y when the prompt appears to start the migration.

It’s designed to be synchronous to avoid Contentful’s rate limiting, so sit back and relax.

Once it succeeds, you’ll never need to run it again!

Important: Keep an eye on the migration. In some cases, Webhook allowed images to be uploaded without a file extension. You’ll notice that these images will fail in the migration. These should be rare — we recommend uploading and linking them manually after the migration.

Step 4 — Try a Webhook Serve!

Your data was successfully migrated over to Contentful! We’ve also done the work required to

wh serve

You should now see a message in your logs like:

webhook2contentful ~~~> Success, we're using contentful!

And (hopefully) your development site will spring up looking identical to the old infrastructure*.

*Please note: Images are now coming directly from the Contentful CDN, rather than the Webhook image proxy. As such — this means your images are now Cross Origin. In most cases, that should be fine, unless you’re using Canvas or something wacky like that. Problems related to that are outside the scope of this project (and can usually be easily fixed).

Important: You’ll need to restart your dev server whenever you change Contentful data to see it propagate locally.

Appendix: Did you see errors?

As mentioned above — it’s possible the migration won’t work for your site out the gate. That likely means your site is using a feature of Webhook CMS that our migration doesn’t cater for.

If you run into problems, please file an issue on the repo, and we’ll get back to you with a fix ASAP!

You can also attempt to fix the issue yourself — that’s why we didn’t go with a Node module. The code is right there (yes, I know it’s super ugly) and you can simply delete your Contentful space, and start again with a fresh one!

Part 2: Hosting (for Developers)

Now that your site is back in working order with a totally different data source, it’s time to move it over to Netlify, so that it can continue rebuilding as content in your new Contentful space changes!

Step 1 — Configure Netlify

1. Login to Netlify
2. Click “New Site from Git”
3. Select “Github” and find your repo (You may need to connect your organization)
4. Configure your build with the following settings (choose “Advanced” and fill in as per your .gitignore)

*Note that the publish directory is “.build”, NOT the default grunt folder.

5. Hit “Deploy site”! Your website will now be deployed using Contentful & Netlify!

Part 3: Editing Content (for Users)

This document wouldn’t be complete unless we touch on a few of the key differences between Contentful & Webhook CMS for our content editors, so here we go!

1. Understanding Contentful & Netlify

We chose Contentful & Netlify because the combination of the two is very similar to how Webhook CMS worked — plus, they are heavily used by the development community, and highly unlikely to go anywhere anytime soon.

For clarity:

• Contentful is your CMS
• Netlify is your Web hosting

Whenever you change anything in Contentful, you’ll need to manually tell Netlify to rebuild your site, so that it can refresh and incorporate your new content. We’ll explain below!

2. Editing your Content

In Contentful, all content is organized by “Models”. “Models” are the types of different of content, and they are all interlinked (just like Webhook CMS!).

If you’d like to edit content, you’ll want to first filter your content by it’s Type, and then search in the search box to find that specific content blob.

Tip: If you’re struggling to find a small blob of content that you know is in there somewhere, perhaps try finding it’s parent, and then drilling down from there.

Once you’ve found the content blob you’d like edit, make the changes, and you’ll see the “status” button on the right side change to “Publish changes”. Go ahead and hit that button — it’s not going to instantly change your site at this point.

3. Deploying your New Content

Once you’ve made the changes to your content, you’ll need to manually signal to Netlify (your host) that you’d like to push those changes live (Unlike Webhook CMS, it doesn’t happen automatically).

Look for the blue “Build” button, and press it! It should load for about 20 seconds, and eventually finish.

Hit “Open preview” to go to your site and click around to see your changes!

3. Editing “List Item” Content

One of the big differences between Contentful and Webhook CMS is that there no “List Item” widget in Contentful. If your Webhook CMS setup was using an embedded “List Item” widget in it’s content types, you’ll now instead see some content types that end with “Subitem”.

An example might be if you had a “Product” that had a list of “Variants”. In Webhook CMS, you’d just have a Product type, and it would have a “List” of variants in that same page.

In Contentful however, it will look more like this:

1. Product has a relation called “Variants”
2. “Variants” can link to many “Variants Subitems”

And it should look something like this:

• Click into one of the Subitems if you’d like to edit it!
• Click “Create Variants Subitem and link” if you’d like to add to the List.

4. Editing Site Settings

You may remember that your old Webhook CMS had a section separate to the Content area called “Settings”. Contentful doesn’t make any distinction between those, so if you’d like to edit those settings, you’ll instead want to find a content model called “Site Settings”.

You can filter for it in the content type dropdown, like so:

Just edit those settings like you’d edit anything else, and don’t forget to press the blue “Build” button after you’ve published them!

4. I think that’s it!

You should be now ready to keep editing and working on your new website. If you have further questions about Contentful & Netlify, do let us know! We’ll add that detail here too, so others can benefit from it.

Thanks so much!

Hugh & Sanctuary Computer