Skip to main content

Creating a New Drupal Project

Clone the Repository​

To start a new project, clone one of the following repositories:

git clone [email protected]:pantheon-upstreams/decoupled-drupal-10-composer-managed.git
_pantheon

The following guide assumes that you are intending to deploy the Drupal site on Pantheon.

Choosing an Approach​

Use Build Tools if:​

  • Testing is an important part of your workflow

  • You don’t want to manually push changes to your code repo.

Use Dashboard Upstream if:​

  • You require a simpler setup

  • The Pantheon repository is your source of truth

Installing using Dashboard Upstream​

  • Create from Decoupled Drupal Composer Managed upstream:

    • Via the Pantheon Dashboard at this link:

    • Or Alternatively via Terminus:

      • Drupal 9
        terminus site:create my-new-site "Describe Site" --org='My Team Name' c76c0e51-ad85-41d7-b095-a98a75869760
      • Drupal 10
        terminus site:create my-new-site "Describe Site" --org='My Team Name' 19a917a4-c56e-44d6-98a1-49e7f779e678
    note
    • Replace '{My Team Name}' with your team name - for example My Agency. This can also be omitted.
    • c76c0e51-ad85-41d7-b095-a98a75869760 is upstream_id for Decoupled Drupal Composer Managed.

Install Drupal:​

Visit the Site by clicking on the Visit Development Site button to Install via the UI—selecting the Pantheon Decoupled Profile install profile. The same can be done via terminus remote:drush.

Install Drupal with Umami Demo Data:​

Visit the Site by clicking on the Visit Development Site button to Install via the UI—selecting the Demo: Umami Food Magazine install profile. After installing, enable the Pantheon Decoupled module.

Optionally:

  • Enable caching under Configuration > Development > Performance
  • Enable the desired theme and admin theme

Installing using Build Tools​

Prerequisites​

  • Composer (required for CMS backends): Install Globally
  • Generate machine token & Authenticate into Terminus
  • Install Terminus (3.0.0 above required)
  • Also install the following plugins:
    • terminus self:plugin:install terminus-build-tools-plugin
    • terminus self:plugin:install terminus-secrets-plugin
    • Reload the terminus plugins: terminus self:plugin:reload
    • Clear cache for composer: composer clear-cache
    • Validate that the required plugins are installed: terminus self:plugin:list

Installation​

  • For all steps below

    • Replace {PROJECT_NAME} with your project name - for example decoupled-drupal.

    • Replace '{My Team Name}' with your team name - for example My Agency. This can also be omitted.

    • Build Tools should prompt you for the credentials it needs to create these assets. While GitHub and CircleCI are the defaults, other providers are supported as well. See available services for details.

  • Create your project using the build:project:create command as shown below:

terminus build:project:create \
  --team='{My Team Name}' \
  --template-repository="[email protected]:pantheon-upstreams/decoupled-drupal-composer-managed.git" pantheon-upstreams/decoupled-drupal-composer-managed \
  --visibility private {PROJECT_NAME} \
  --profile="pantheon_decoupled_profile" \
  --stability=dev

Known Issues​

  • If you encounter errors during the Installation process, please check if you have the terminus-power-tools plugin installed. If so you should remove the terminus-power-tools plugin and go through Installation again.

Additional Options​

Using Other Git Hosts or CI Services​

Terminus build tools supports a number of other combinations of git hosts and CI services.

For example, to use GitHub actions as your CI service, you could add the following additional flag to your terminus build:project:create command:

--ci=githubactions

Other possible values are circleci, gitlab-pipelines and bitbucket-pipelines.

Note: if using Github Actions, your token should have the "workflow" scope.

For more information, consult the available services section of the build tools documentation.

Using a GitHub Organization​

--org="{My Organization Name}"

If you would like the repo created to be under a GitHub organization instead of the authenticated user's namespace, you can use the --org option.

For information on additional options, consult the command options section of the build tools documentation.

Completing Your Configuration​

_Pantheon Front-End Sites

The following will be available when the pantheon-decoupled plugin is being used:

Once logged into the development site, a message will display directing you to the Front-End Sites Administration section. Through this administration section, the following steps should be completed to fully configure your project:

  • Edit the example preview site, or create a new preview site. See the instructions for creating a new preview site.
  • In the preview site list, select the Environment Variables action next to your new preview site. Proceed through this modal, generate a new CLIENT_SECRET and copy the generated value. All other environment variables needed to configure your Front-End Site will be displayed in this modal.
  • See your starter kit's related Setting Environment Variables documentation for more information on how to set these variables in your local development environment or on the Pantheon Dashboard.

Updating from Drupal 9 to Drupal 10​

To update a Decoupled Drupal Composer Managed site to Drupal 10, clone the backend site repo and do the following:

  1. Update to PHP 8.1 or greater if you have not already done so, by editing pantheon.yml and adding the following, with your chosen version of PHP:

    php_version: 8.1

  2. Update packages in your composer.json to the appropriate new versions:

    composer config platform.php 8.1
    git commit -am "composer config platform.php 8.1"
    composer config minimum-stability dev
    git commit -am "composer config minimum-stability dev"
    composer require --no-update --dev drupal/core-dev:^10
    composer require --no-update drupal/core-composer-scaffold:^10
    composer require --no-update pantheon-systems/drupal-integrations:^10
    composer require --no-update drupal/core-recommended:^10
    composer require --no-update drupal/pantheon_decoupled_profile:^2
    composer require --no-update drupal/pantheon_decoupled_umami_demo:^2
    composer update
    git commit -am "Update to Drupal 10"

  3. Push the changes up to Pantheon

    git push origin master

  4. If you are updating an existing Drupal install, you will need to run database updates. This can be done with terminus or via the Drupal web UI.

    With terminus:

    terminus drush <BACKEND_SITE>.<ENV> updatedb

    Via the Drupal web UI: Visit /update.php on your Drupal backend site, e.g.

    https://dev-my-decoupled-backend.pantheonsite.io/update.php