Create a Drupal Site Using a Drupal Distribution

Distributions are pre-made packages that you can use to simplify creating and setting up a Drupal website. Drupal distributions are exceptionally helpful if you want to create a website, but don't want to build it from scratch.

Review the documentation provided with the community distribution before following the steps below.

Prepare

Review our documentation on Git, Composer, and Terminus, and install and configure them on your local computer. Pantheon requires Composer 2 at minimum.

• Mac users can use Homebrew to install Git, Composer, and PHP, along with their required dependencies. Note: Terminus 3 should be used for PHP >= 8.0. Restart the shell or terminal environment after entering the following command:

  brew install git composer php

• Windows users can install Composer and Git, and may need to install XAMPP or similar to satisfy some dependencies.

Create a Site Based on an Empty Upstream

There are two ways to create an empty Upstream site: via the Pantheon Dashboard and via Terminus.

• Via the Pantheon Dashboard:

  • Use the Empty Site Upstream

• Via Terminus:

  terminus site:create my-new-site "My New Site" empty

Create the Project

Use the documentation provided with the Drupal distribution to run the recommended Composer create-project command.

You can review a list of commonly used distributions on the Drupal Distributions page.

Add Files and Folders

Now you're going to copy files and folders from the Pantheon GitHub repository for use in your project.

1. Clone https://github.com/pantheon-upstreams/drupal-composer-managed into another folder.

   In the code samples included below, [drupal-composer-managed-path] should be replaced with the location of the cloned repository. In addition, they assume the commands are being run from the folder created from the create-project command.

2. Copy the upstream-configuration folder to your site:

   cp -r /drupal-composer-managed-path/upstream-configuration .

3. Copy the pantheon.upstream.yml file to your site:

   cp  /drupal-composer-managed-path/pantheon-upstream.yml .

4. Create an empty config folder:

   mkdir -p config .

Update Composer Settings

Add/modify the settings in composer.json as follows, replacing the Drupal values with the latest version:

1. Add the upstream-configuration path repository:

   composer.json

   "repositories": [
       {
           "type": "composer",
           "url": "https://packages.drupal.org/8"
       },
       {        "type": "path",        "url": "upstream-configuration"    }],

2. Include the following in the require section:

   composer.json

   "require": {
       "pantheon-upstreams/upstream-configuration": "dev-main",
       "pantheon-systems/drupal-integrations": "^9",
       "drush/drush": "^11 || ^12"
   },

3. Add pantheon-systems/drupal-integrations and Quicksilver scripts (optional) to extra:

   composer.json

   "extra": {
       "drupal-scaffold": {
           "locations": {
               "web-root": "./web"
           },
           "allowed-packages": [            "pantheon-systems/drupal-integrations"        ],        "file-mapping": {
               "[project-root]/.editorconfig": false,
               "[project-root]/pantheon.upstream.yml": false,
               "[project-root]/.gitattributes": false
           }
       },
       "installer-paths": {
           "web/core": ["type:drupal-core"],
           "web/libraries/{$name}": ["type:drupal-library"],
           "web/modules/contrib/{$name}": ["type:drupal-module"],
           "web/profiles/contrib/{$name}": ["type:drupal-profile"],
           "web/themes/contrib/{$name}": ["type:drupal-theme"],
           "drush/Commands/contrib/{$name}": ["type:drupal-drush"],
           "web/modules/custom/{$name}": ["type:drupal-custom-module"],
           "web/profiles/custom/{$name}": ["type:drupal-custom-profile"],
           "web/themes/custom/{$name}": ["type:drupal-custom-theme"],
           "web/private/scripts/quicksilver/{$name}/": ["type:quicksilver-script"]    },
       "composer-exit-on-patch-failure": true,
       "patchLevel": {
           "drupal/core": "-p2"
       }
   },

4. Add autoload.classmap:

   composer.json

   "autoload": {
       "classmap": [
           "upstream-configuration/scripts/ComposerScripts.php"
       ]
   },

5. Add these scripts and scripts-description sections:

   composer.json

   "scripts": {
       "pre-update-cmd": [
           "DrupalComposerManagedComposerScripts::preUpdate"
       ],
       "upstream-require": [
           "DrupalComposerManagedComposerScripts::upstreamRequire"
       ]
   },
   "scripts-descriptions": {
       "upstream-require": "Add a dependency to an upstream. See https://docs.pantheon.io/create-custom-upstream or information on creating custom upstreams."
   },

Update settings.php

Add the following to your /web/sites/default/settings.php file.

include __DIR__ . "/settings.pantheon.php";

Initialize, Push, and Test

1. Initialize the git repo and commit everything:

   git init -b master
   git commit -am "Initial commit"

2. Add the Pantheon repository as a remote:

   git remote add origin [pantheon_remote]

   If you need to get pantheon_remote, use Terminus:

   terminus connection:info --field=git_url [site].dev

3. Force push to Pantheon master branch:

   git push origin master -f

4. Install your site in the dev environment and test that everything works.

More Resources

• Get Started

• Drupal Migration Guides

• Go Live