Cloud Platform
Node.js with Decoupled Drupal on Cloud Platform
Build and deploy a decoupled application using Drupal and Node.js on Cloud Platform.
Note: This repo uses an older version of Drupal 8 and requires the JSON:API module. It's a good example of how to get started with Node.js, but do not use it as the base for a new project. Newer projects should include the latest release of Drupal 8 and Drupal 9. These versions include JSON:API as part of core.In this tutorial you'll learn how to build a Decoupled Drupal application with Node.js on Cloud Platform. We'll guide you through the development and deployment of a Decoupled Architecture hands-on and step-by-step.
An API-first or Decoupled Drupal application can offer many benefits to a broader development base than a traditional CMS structure. You need to understand the core concepts of this workflow in order & to form a cohesive development plan.
We'll achieve this goal by leveraging the provided codebases for both the Drupal and Node.js applications, which are designed to work together. These two separate applications will demonstrate a standard workflow with the inherent relationship created by content offered by the Drupal API.
The tutorial includes three in-depth lessons:
This tutorial is also offered as a video walkthrough for learners:
Understand the core workflow of a decoupled architecture.
Before diving into the technical steps, let s understand the high-level design of the architecture itself. A "headless" or "decoupled" Drupal architecture typically involves the communication between two separate applications: a Drupal website (acting as a data source) and a front-end application (acting to display data provided by Drupal). For the purposes of this tutorial, we will use a Node.js based front-end application.
Project requirements often help to surface benefits of leaning on a decoupled Drupal architecture. These project requirements usually revolve around the intent of an "API-first" methodology. API-first Drupal can be contextually understood as leveraging the CMS to expose data for consumption in another application. Benefits of this architecture typically revolve around the desire to store data in Drupal, while offering options of displaying that same data in other locations outside of Drupal.
The core function of Drupal within the decoupled architecture to serve as a data source, but that role could translate into a couple of different things. There are project scenarios in which the Node.js application is intended to emulate the content type fields and mirror the data in the same manner. Some project requirements indicate that selected content combine to offer promotional or real-time updates. While there are a wide range of technical purposes, the end result of this scenario is typically structured around the housing of data. In this case a "data source" should be interpreted for both database storage and data construction patterns.
The role of Node.js within our decoupled architecture is two-fold: presenting data that is ingested from Drupal and sending data back to Drupal. In most cases, the Node.js application core focus serves the application and displays data from Drupal. This is not a suggestion that the application pulls data from Drupal solely, but for the purpose of this tutorial we will make this assumption. This need is a key driver for the adoption of Node.js as the abstracted presentation layer.
Structure a local Drupal website and a local JavaScript application for a decoupled architecture.
In this lesson, we will stand up a pre-built Drupal website locally using some common Acquia build tools Acquia BLT (Build and Launch Tool) & Drupal VM. The Drupal sample content and fields demonstrate a clear correlation between Drupal and the JavaScript application, allowing for easy extensibility.
In order to complete this lesson you will need to have the following software packages installed:
You'll also need PHP CLI version 7.3 or greater installed in order to complete the installation. On MacOS the easiest way to install PHP is with Homebrew.
For a complete list of prerequisites and more extensive setup instructions, refer to the BLT onboarding and DrupalVM quick-start documentation.
Download the Drupal codebase by cloning the repository with:
git clone https://github.com/acquia/decoupled-drupal.gitOnce the code has finished downloading, cd into the folder with:
cd decoupled-drupal/From this location, install the package dependencies with:
composer installFor the next steps, set up the local Drupal site with BLT & Drupal VM to expedite the process. These steps can also be accomplished with a standard local LAMP stack or a similar preference, with the assumption of maintaining the same localhost name (local.decoupled.com).
From the same decoupled-drupal/ folder location, install the BLT alias:
composer run-script blt-aliasSetup your local virtual box with Drupal VM, using the BLT command:
blt vmThis will indicate a question Do you want to boot Drupal VM?, which you can type "y" to proceed. You might want to get a cup of coffee while this completes.
Build and install the Drupal installation with:
blt setupCD into docroot/ and log into your Drupal application with:
drush @decoupled.local uliIf you are seeing errors with the uli command or do not see the alias with the drush sa command, you can also shell into the vagrant box. To proceed with this workaround, follow these instructions:
> vagrant ssh
> cd docroot/
> drush uliYou can now review the test content at http://local.decoupled.com/admin/content.
The next steps involve setting up a previously constructed JavaScript application to work in tandem with our local Drupal application. Follow this step only after your local Drupal codebase and site is set up. For our example JavaScript application, Node.js is leveraged to create the pages, while using the Ember.js framework to pull the API data.
Install the following software packages (if not previously installed):
Download the JavaScript codebase by cloning the repository with:
git clone https://github.com/acquia/decoupled-js.gitOnce downloaded, cd into your application root with:
cd decoupled-js/We will now install the required node modules with:
npm installNow that the installation is complete, serve and view the JavaScript application locally at http://localhost:8080 with:
npm startYou can now view your Node.js application which is displaying the content from Drupal!
The two local applications are intended to display the scenario of a "Decoupled Drupal" architecture. The Drupal CMS website serves as a data source to collect data. The Drupal content types and fields are used to structure the data.
Once the data has been structured and created, it is then exposed through an API endpoint in Drupal. The purpose of the API endpoints is to allow data to be used within our JavaScript application. In common scenarios, you could allow data to be sent back and stored into Drupal. For this tutorial, we are only pulling data from Drupal.
The Drupal application is built using the "Headless Lightning" distribution as its functional baseline. Headless Lightning is a more opinionated sub-profile of the popular Lightning Drupal distribution intended to be used as a back end for decoupled applications. It includes two primary features: the Lightning Content API, and a Headless UI. The Lightning Content API (which is also included in the standard Lightning distribution) exposes Drupal entities via a JSON-based REST API. The Headless UI simplifies the Drupal administrative back end and content authoring experience to be more accessible to users who might be less familiar with Drupal's administrative patterns.
The Drupal application provides two content types ("Cats" and "Dogs") and populates them with sample data. Each of the content types have a handful of fields for data collection.
The various content nodes are then exposed as API endpoints using the JSON API module. These nodes can be viewed as a collection for that content type or by individual ID based on selection. While most content scenarios are addressed with the node patterns like /jsonapi/node/{content\_type}, others warrant combining user information as /jsonapi/node/{content\_type}/{uuid}.
The Node.js application is a collection of modules which uses specific functionality separately for a web server and the application itself:
Since the core functionality of the application revolves around ingesting an external API, the application uses the Ember Data library. Ember Data does a great job of handling the persistence of the data model, regardless of record origin. The application validates and maps records according to the Drupal entities by routes according to the JSON API standards for the pertinent URL (jsonapi/node/{nodetype}). The records are then parsed appropriately with the associated routes by querying the ID.
Deploy Drupal and Node.js applications to Cloud Platform
To complete this lesson you need access to an Cloud Platform environment with both a Drupal and a Node.js dev environment
With the Drupal and JavaScript applications available locally, we will focus next on the deployment of these applications. While steps slightly vary for each application, the same workflow methodology applies when deploying a build artifact to the Cloud Platform.
To complete the next tasks, you will need to add the Cloud Platform Git URL as a remote using the following command.
Locate the Git URL under the "Information" section in your Cloud Platform Subscription:
Add the URL as a Git remote:
git remote add cloud YOUR_CLOUD_GIT_URLThe new git remote has been added. Switch to the master branch of this location for each application.
Acquia Pipelines will now create the build artifact. If you have not set up Acquia Pipelines locally, follow the steps outlined in this tutorial.
To build an artifact for both applications, add a acquia-pipelines.yaml file in the respective root of each codebase. An example of the acquia-pipelines.yaml file for Drupal is available at this reference and the example for Node.js is found at this reference.
There may be the need to set the default Application ID for your local repository to properly associate the artifact to the subscription. Use pipelines list-applications to find the ID for your Cloud Platform application, then set the ID with pipelines set-application-id --application-id=[application-id].
Now that everything is configured appropriately, you can build your artifact with:
pipelines startOnce the artifact is built, deploy the artifact to your environment within the Cloud UI. This can be accomplished by going to the "Environments" tab and choosing "Switch" for the proper build artifact. You can see a full explanation of the process at the Code workflows documentation.
Deploying the artifact to the Cloud Platform can be accomplished by following the same workflow as the Drupal deployment steps. Go to the "Environments" tab and click the "Code" element icon. This will allow you to switch the artifact to based on a hash number. You can view the complete steps for deploying your application in the Deploying build artifacts in your Node.js environment documentation.
Congratulations! You have deployed both applications to the appropriate Cloud Platform environments and are ready for review.
Cloud Platform