Connecting to Drupal

This guide will show you how to connect your Gatsby Cloud site to Drupal via manual configuration.

Prerequisites

This guide assumes you already:

• have a Gatsby project in a GitHub repository
• have a Drupal backend with content that your Gatsby project understands
• are familiar with how to create a Gatsby Cloud site from a repository
• are familiar with how to install Drupal modules

If you are unfamiliar with how to install Drupal modules, checkout Drupal's guide.

If you are starting a Gatsby project from scratch, check out the Create a Site from a Template tutorial instead.

1. Configure Environment Variables

In Gatsby Cloud, start creating a site using the Import from a Repository flow. Once you reach step 5, "Configure Environment Variables," add any environment variables necessary for the site to build.

If you have enabled authentication for your Drupal instance, you will want to add any necessary environment variables (e.g. DRUPAL_USERNAME, DRUPAL_PASSWORD, etc.), so that Gatsby Cloud can expose these variables to your application.

2. Configure Webhooks

To live-preview content from Drupal, you will need to do several things, specifically:

1. Install the “Gatsby Live Preview & Incremental Builds” module
2. Enable the Gatsby, Gatsby JSON:API Extras, and Gatsby JSON:API Instant Preview and Incremental Builds modules in Drupal.
3. Copy the webhooks from Gatsby Cloud to your Drupal Gatsby module settings.

Doing each of these allows Gatsby Cloud to receive content updates from Drupal without refreshing or rebuilding. Excellent! Let’s get started.

3. Install the Gatsby Module in Drupal

You can install the Gatsby Live Preview Module via the command line or the Drupal Admin.

Install via Command Line

If you know how to install modules through the command line, you can use Drush

drush en gatsby

or Composer

composer require drupal/gatsby

Install via Drupal Admin

First, visit the the Gatsby Live Preview project on Drupal.org. In the Downloads section at the bottom of the page, copy the URL for the tar file containing the module.

Next, log into your Drupal admin interface. Then, go to the Manage > Extend tab.

Press the Install new module button and enter the module URL you copied previously into the Install from a URL field. Then click the Install button.

Installing this module will also install the JSON:API module if you haven’t already installed it.

Finally, to install, we’ll select the Gatsby, Gatsby JSON:API Extras and Gatsby JSON:API Instant Preview and Incremental Builds modules in our Extend view and press the “Install” button.

4. Configure the Gatsby Module in Drupal

You'll need the following values from Gatsby Cloud to configure the Gatsby module in Drupal:

1. Gatsby Preview Server URL
2. Preview Webhook
3. Builds Webhook

In Gatsby Cloud, go to the CMS Preview tab for your site then copy the preview instance URL. This is the Gatsby Preview Server URL in Drupal. 

In Gatsby Cloud, go to Site Settings -> General -> Webhook to obtain your Preview Webhook and Builds Webhook.

In Drupal Admin, go to Configuration -> Web Services -> Gatsby Settings (/admin/config/sevices/gatsby/settings).

Put in the values you grabbed above into the following fields:

1. Gatsby Preview Server URL is the URL of your Preview in Gatsby Cloud
2. Gatsby Preview Callback URL is the Preview Webhook from Gatsby Cloud Site Settings -> Webhooks
3. Incremental Build Server Callback Hook(s) is the Builds Webhook from Gatsby Cloud Site Settings -> Webhooks

You'll also need to check which entity types to send to Gatsby Preview and Build Server. At a minimum, you should select "Content" and click Save Configuration.

4. Finish

With that, everything is properly configured and your Gatsby Cloud Builds and CMS Previews will update when your content changes.

You can confirm this by editing and saving content in Drupal and then viewing the logs in your Gatsby Cloud site. You should see a log that says "Data Update from Drupal":