Tutorial Goal
Build and deploy a decoupled application using Drupal and Node.js on Cloud Platform.
Tutorial Overview
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:
- Understanding the architectural workflow
- Setting up a local Drupal and Node.js application
- Deploying your applications to Cloud Platform
This tutorial is also offered as a video walkthrough for learners:
- Node.js with Decoupled Drupal on Acquia Cloud: Local Set Up
- Node.js with Decoupled Drupal on Acquia Cloud: Deploy
Understanding the architectural workflow
Lesson Goal
Understand the core workflow of a decoupled architecture.
Introduction
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.
Benefits of a Decoupled Architecture
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.
Role of Drupal in a Decoupled Architecture
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.
Role of Node.js in a Decoupled Architecture
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.
Setting up a local Drupal and Node.js application
Lesson Goal
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 and Install Code Dependencies
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 install
Stand up the local Drupal instance
For 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.
Setting up the Node.js Application locally
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):
For a complete list of prerequisites and setup instructions, refer to the decoupled-js README.
Download and install the Application
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!
Overview of Current Architecture
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.
About the Drupal Application
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}.
About the Node.js Application
The Node.js application is a collection of modules which uses specific functionality separately for a web server and the application itself:
- The ‘/server’ folder is designated to create a web server in which the application will layer upon. The ‘server.js’ file uses the express.js web application framework to serve the application on port 8080 on your local machine.
- The ‘/client’ folder is designated for the application’s functionality that will interact with the content served from the Drupal API.
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.
Resources
Deploying your applications to Cloud Platform
Lesson Goal
Deploy Drupal and Node.js applications to Cloud Platform
Overview and Configuration
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.
Creating the deploy artifact with Acquia Pipelines
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 startDeploying the Drupal codebase
Once 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 JavaScript codebase
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.
Resources
Congratulations! You have deployed both applications to the appropriate Cloud Platform environments and are ready for review.