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 either the Pantheon Decoupled Profile, or Pantheon Decoupled Umami Demo profiles. The same can be done via terminus remote:drush.

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​

Installing with Umami Demo Data​

The installation command above will create a backend with limited example content. To instead create a site with Drupal's Umami demo data set, change the profile flag to:

--profile="pantheon_decoupled_umami_demo"

In your terminus build:project:create command.

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.

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 back-end site, e.g.

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