Get started with Kickstart

This project is a Drupal installation profile that is added to Drupal core and installed using Composer. The installation instructions below use the Apigee Developer Portal Kickstart Composer project to install Drupal core and this installation profile to create a new developer portal site.

Prerequisites

Before getting started, you will need to make sure you have these tools installed:

• Git
• Composer
• PHP
• Web server
• Database server

Read Before a Drupal installation section of the Installing Drupal guide to learn more on installing Drupal prerequisites. Reading Using Composer to Install Drupal and Manage Dependencies is also a good idea to understand how Kickstart is being managed using Composer.

Installation Instructions

Warning: When installing Kickstart, the Edge connection settings are stored in Drupal’s configuration system which is not designed to store sensitive information. When installing Kickstart for uses other than local development, we highly recommend changing the Apigee Edge connection key provider to a more secure storage location. Learn more

To download Drupal Core 10, the Apigee Developer Portal Kickstart profile, and all dependencies into the MY_PROJECT directory:

1. Execute the following command:

   - For Drupal 10:
   composer create-project apigee/devportal-kickstart-project:10.x-dev MY_PROJECT --no-interaction

   Note : Refer the documentation for upgrading from Drupal 9 to Drupal 10.

   Note that the -dev in the command above lets Composer know that we want to use the 10.x branch in the devportal-kickstart-project-composer GitHub project instead of a tag. It will always install the latest stable release of Drupal Core and the Kickstart distribution. See Composer branch alias documentation for more information.

2. The actual web root will be MY_PROJECT/web. Point your web server to serve that directory.

3. Visit the site in a web browser, and you'll be redirected to core/install.php, where you can run the installer like any Drupal site installation. Running the installation via web browser is recommended for the best experience.

4. If you are installing Kickstart for use with a Monetization-enabled Apigee org and you are using the latest version of the apigee/devportal-kickstart-project in your main composer file, the installer prompts you to enable Monetization.

   • If you enter connection details for a Monetization-enabled Apigee org and you are not prompted to enable Monetization, see updating your main composer file to confirm you are using the latest version of Kickstart.

   • If you are using your own composer file and you want to enable Monetization, use the following command to add apigee_m10n to your project before running the web base installer:

     composer require drupal/apigee_m10n drupal/commerce:"^2.16" --optimize-autoloader

     The “--optimize-autoloader” flag is optional in the above command.

   For more information on using the Apigee Monetization module for Drupal with the Kickstart distribution, see Enable Monetization.

Note: The composer create-project command shown above creates a main composer.json file that includes the Monetization and Commerce modules. If you are not using Monetization in your Kickstart portal, you can run the following command to remove these modules from the file:

composer remove drupal/apigee_m10n drupal/commerce

Alternate Installations

You can always follow standard Drupal install instructions if you do not have an AMP stack (Web server, Database, and PHP), but here are some other ways to get an AMP stack up and running:

Alternative Installation: Using Drupal Quick Start

Alternatively, you can use the composer quick-start script to run the Drupal Quick Start Command, as shown below:

cd MY_PROJECT
composer quick-start

This command will install Drupal using PHP's built in web server and a SQLite database.

Note: While quick-start is the fastest means of installing this profile, it is not the most performant or complete. It does not present the configuration options available when installing via web browser. As a result, you'll need to configure the Apigee Edge connection manually, post installation. See Apigee Edge documentation for more information.

Alternative Installation: Using Lando for Local Development

You can get a local development running quickly using Lando instead of setting up a database, PHP, and a web server on your local machine.

Prerequisites

To install and run the Apigee Developer Portal Kickstart distribution in your local development environment, make sure you have the following tools installed:

Install Drupal

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

1. From your project directory, execute the following command, replacing apigee-kickstart with your preferred project name.

   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.

   // For Drupal 10:
   composer create-project apigee/devportal-kickstart-project:10.x-dev apigee-kickstart --stability dev --no-interaction
   

   This command creates a new directory named apigee-kickstart in your project directory and installs the Apigee Developer Portal Kickstart and all dependencies in the web directory. Review the README file in the apigee-kickstart directory for more details about the installation.

Run Drupal

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 generating 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.

1. Run the lando init command and respond to the prompts, as shown in bold. The lando init command creates a .lando.yml file in the root directory.
   Note: If installing Drupal 9, replace the recipe drupal8 with drupal9 in the command below.

   $ cd apigee-kickstart
   $ lando init --recipe=drupal8
   ? Where is your webroot relative to the init destination? web
   ? What do you want to call this app? apigee-kickstart
   
   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      apigee-kickstart                                          
    LOCATION  /Users/chet/projects/apigee-kickstart           
    RECIPE    drupal8                                            
    DOCS      https://docs.devwithlando.io/tutorials/drupal8.html

2. 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.

3. The lando start command prints the URLs for the application. Copy the non-HTTPS hostname URL and open it in your browser to run the installer. For example:

   http://apigeekickstart.lndo.site

4. 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 preferred language from the drop-down. Click 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: drupal Database username: drupal Database password: drupal Advanced Options-Host: database Click Save and continue.
   Install site	A progress bar displays while the site is installed.
   Configure site	Configure your site with the administrator login and password information, as required. Click Save and continue.

5. The default home page is displayed.

6. Configure the connection to Apigee Edge, as described in the Apigee Edge module documentation.

Upgrading Kickstart

Drupal has information on using Composer and how to update a site using Composer, but here is a quick guideline:

1. Make sure you're running the latest version of composer:
   

   composer self-update

2. Go to the root of your site:
   

   cd /path/to/kickstart

3. Run the following command to update all packages, where the --with-dependencies flag will update all dependencies of your project's dependencies, and optionally --optimize-autoloader to speed up performance:
   

   composer update --with-dependencies --optimize-autoloader

4. Next, run any database updates (cd into the web directory first):
   

   cd /path/to/kickstart/web
   ./vendor/bin/drush updb

5. Clear the Drupal cache (cd into the web directory first):
   

   ./vendor/bin/drush cr

Updating Your Main Composer File to Use drupal/recommended-project

When you run composer install, Composer will download and install the apigee/devportal-kickstart-project-composer project. The apigee/devportal-kickstart-project-composer project is based on drupal-composer/drupal-project, but as of April 9, 2020,  drupal/recommended-project  is used as a starting point (see PR#24 for details). If your project was created before April 9 2020, you may want to consider replacing your main Composer file with the latest version.  To use the latest version:

1. Backup your original composer.json file.
2. Copy over the latest composer.json file from apigee/devportal-kickstart-project-composer.
3. Re-add any Drupal modules to the new composer.json file or changes you made from the backup composer.json file. It may be useful to view the diff of changes moving to the drupal/recommended-project composer file.
4. Run composer update --with-dependencies --optimize-autoloader.

Troubleshooting Memory issues with Composer

You may run into memory issues running composer. There are multiple approaches to solving Composer memory errors, but a simple solution is to set a memory limit for Composer as an environment variable on your machine or server. For example, you can add this line to your .bash_profile, .bashrc or equivalent file:

export COMPOSER_MEMORY_LIMIT=2G