Build your portal using Drupal 8 (Beta)

Drupal 8 provides a reliable open-source, enterprise-level content management system (CMS). Using the Drupal 8 portal development tools, you can build a fully customizable developer portal. Because Drupal 8 is open-source, you can extend and contribute to the Drupal 8 portal development framework and leverage the knowledge of the Drupal community.

The following sections describe how to use Drupal 8 to developer your portal.

Install and run Drupal 8 in your local environment

The following section describe how to install and run Drupal 8 in your local environment.

Note: The Apigee Edge module requires Drupal 8.5.x or higher and PHP 7.1 or higher.

Prerequisites

To install and run Drupal 8 in your local development environment, you need to install the following tools:

Composer Composer enables you to install Drupal modules with all of the required dependencies. Because the Apigee Edge module requires the Apigee Edge Client Library for PHP, it is recommended that you install Drupal 8 and its modules using Composer to facilitate and manage these dependencies.
Lando Lando enables you to set up the infrastructure needed to run a Drupal CMS in your local environment using Docker containers.

Install Drupal 8

There are several options available for setting up Drupal 8 using Composer, as described in Using Composer to manage Drupal site dependencies. The following procedure uses the Composer template for Drupal projects.

  1. Open a terminal window and create a directory names projects.
  2. Change (cd) to the projects directory.
  3. Execute the following command:
    Note: You may need to replace composer with php composer.phar in the following command example if Composer is not in your PATH. See Installing composer globally to move Composer in your PATH.

    composer create-project drupal-composer/drupal-project:8.x-dev d8-devportal --stability dev --no-interaction

This command creates a new directory named d8-devportal in the projects directory and installs Drupal 8 and all dependencies in the web directory. Review the README file in the d8-devportal directory for more details about the installation.

Run Drupal 8

To run Drupal, you need to install a web server configured with PHP so that server requests are passed to Drupal’s PHP code for processing and to generate a response. Lando enables you to quickly set up a Nginx web server already configured with PHP to host Drupal in your local environment using Docker containers.

Run the lando init command and respond to the prompts (shown in bold). This commands creates a .lando.yml file in the root directory.

$ cd d8-devportal
$ lando init --recipe=drupal8
? Where is your webroot relative to the init destination? web
? What do you want to call this app? devportal

NOW WE'RE COOKING WITH FIRE!!!
Your app has been initialized!

Go to the directory where your app was initialized and run
`lando start` to get rolling.

Check the LOCATION printed below if you are unsure where to go.

Here are some vitals:

 NAME      devportal                                           
 LOCATION  /Users/chet/projects/d8-devportal             
 RECIPE    drupal8                                             
 DOCS      https://docs.devwithlando.io/tutorials/drupal8.html 

Run the following command to start the server:

$ lando start

Note: Before starting the server, you may want to disable metrics tracking in the ~/.lando/config.yml file.

The command prints out the URLs for the application. Copy the the non-HTTPS hostname URL and open it in your browser to run the installer. For example:
http://devportal.lndo.site

Respond to the prompts to configure and install the server.

Note: Run lando info to view the database host name, username, password, and connection URLs.

Configuration Description
Choose language Choose your language from the drop-down (for example, English) and click Save and continue.
Choose profile Select the Standard installation profile and select Save and continue.
Set up database Enter the following values to set up the database:
  • Database type: MySQL, MariaDB, Percona Server, or equivalent
  • Database name: drupal8
  • Database username: drupal8
  • Database password: drupal8
  • Advanced Options-Host: database
Click Save and continue.
Install site A progress bar displays while the site is installed.
Configure site Configure your site including administrator login and password information, as required, and click Save and continue.

The default home page is displayed.

Next, you need to install the Apigee Edge module to integrate your Drupal site with Apigee Edge.

Install and configure the Apigee Edge module

Integrate your Drupal 8 developer portal with Apigee by installing and configuring the Apigee Edge module.

Integration with Apigee Edge

The developer portal does not function as a stand-alone system. Much of the information used by the portal is actually stored on Apigee Edge.

The Apigee Edge module that is installed on the portal acts as a client for Apigee Edge. Using the credentials that you configure, the portal initiates communication with Edge by making REST requests over HTTP and HTTPS. For example, when a developer registers a new app on the portal, the portal makes a request to Edge to send information about the app to Edge.

To install and configure the Apigee Edge module:

  1. In the terminal window, from the d8-devportal directory install the Apigee Edge module using Composer:
    composer require drupal/apigee_edge

  2. In your browser, click Extend in the Drupal administration menu.

  3. Select the Apigee Edge module.
    Optionally, enable the following modules:

  4. Click Install.

  5. Configure the connection to Apigee Edge.

Build your portal

Build your portal using Drupal 8. For assistance, refer to the following sources:

Publish your API documentation

To render your OpenAPI Specification in Swagger UI, you can use the Swagger UI Field Formatter module. This module can be used to publish API Documentation created using Swagger or Open API Specification, on any Drupal site.

For more information, see Document your APIs using the Swagger UI on the Drupal.org site.

Choose your hosting provider

Choose a provider to host your developer portal, such as Pantheon, Acquia, or another provider.

Get started with Pantheon

This section describes how to set up a local Pantheon site and install the Apigee Edge module on Pantheon.

To install the Apigee Edge module you must use Composer to ensure all dependencies are downloaded and installed. Since you cannot run Composer directly from your Pantheon site, you need to check in to your site all files downloaded by Composer. This is required only if you are not able to run Composer directly on the server hosting your site, which is the case for Pantheon sites.

You can use one of the following methods to set up Pantheon as your hosting provider.

Method Description
Composer without contiguous integration Set up a local Pantheon site quickly using Composer. Push updates to Patheon. This method is described in this section.

Note: You will not be able to apply Drupal core updates using the Drupal site dashboard. To manage production environments, this method is recommended for advanced users only.

Composer with contiguous integration Set up a development site to make it easy for your team to follow development best practices, such as using pull requests and automated testing. For more information, see the Pantheon build tools guide.

Set up a Drupal site on Pantheon using Composer without contiguous integration

Note: Ensure that you have installed Composer and Terminus.

To set up a new Drupal site on Pantheon, in Drupal 8 and Composer on Pantheon Without Continuous Integration complete the steps up to and including "Installing Drupal." The other steps in the section are not required to set up a new Drupal site on Pantheon, but will help you understand the workflow for other tasks.

Install Apigee Edge Module

To install the Apigee Edge module, use Composer. Pull down (git clone) the latest code to your local machine and run Composer:

composer require drupal/apigee_edge

Note: If you get an error reporting an incompatible PHP version, use the --ignore-platform-reqs flag to ignore the version:
composer require drupal/apigee_edge --ignore-platform-reqs

Check the pantheon.yml file in your root directory to ensure that the PHP version is set to 7.1 or higher, which is required by the Apigee Edge module. PHP 7.1 and 7.2 are both supported by Pantheon:

api_version: 1
web_docroot: true
php_version: 7.2
...

Add the new files to the repo by executing the following commands:

git add .
git commit -m 'Added Apigee Edge Module'
git push 

Enable the Apigee Edge module using one of the following methods:

  • Log in to your Drupal site as an administrator, select Extend, select the Apigee Edge module, and click Install.
  • Run the following Terminus command (replace $PANTHEON_SITE_NAME with the actual value, in this case):
    terminus drush $PANTHEON_SITE_NAME.dev -- en -y apigee_edge