Create a New Project

This section provides information on how to use the Drupal Backend Starter for Front-End Sites.

Choose How to Create the Project

You can create your backend starter kit project with the Dashboard Upstream, the Terminus Decoupled Kit Plugin, or with Build Tools.

Review the following sections to select the right option for your setup.

Use the Dashboard Upstream if:

• You require a simpler setup.
• The Pantheon repository is your source of truth.

Use the Terminus Plugin if:

• You want to create a related backend and frontend codebase in a single process.
• You prefer to use the CLI.

Use Build Tools if:

• Testing is an important part of your workflow.
• You don’t want to manually push changes to your code repository.

Create with Dashboard Upstream

1. Go to the workspace, that the new site should be a part of, then select the Sites page.

2. Click +Create New Site.

3. Select Front-End Site when prompted.

4. Select Drupal for Front-End under Create Backend CMS.

   • You can also follow the Decoupled Drupal Composer Managed link to create your site in the Site Dashboard.

   

5. Name your site, select your decoupled environment from the Choose a Workspace for the Site drop-down menu, and then click Continue.

   Site and Multidev names cannot contain a . (period) or _ (underscore).

   • To do this step through Terminus, replace my-new-site, the site description, and the org (if available) in My Team Name in the following command:

     terminus site:create my-new-site "Describe Site" --org='My Team Name' c76c0e51-ad85-41d7-b095-a98a75869760

     Note that c76c0e51-ad85-41d7-b095-a98a75869760 is the upstream_id for Decoupled Drupal Composer Managed.

6. Confirm your organization selection when prompted in Confirm Organization Selection. The Deploying Decoupled Drupal Composer Managed progress indicator displays while your site is being created.

7. Click Visit your Pantheon Dashboard when the site creation completes.

8. Click the Visit Development Site button to install Drupal.

9. Select the Pantheon Decoupled Profile install profile. The same can be done via terminus remote:drush.

Your backend starter is ready to develop!

Create with Terminus Plugin

Terminus is a command line interface that provides advanced interaction with Pantheon. You can create your project with the Terminus Decoupled Kit Plugin if you prefer to work in the terminal.

The Terminus Decoupled Kit plugin provides commands useful for creating decoupled projects on Pantheon using pre-configured starter kits.

The steps in this section show how to use the Front-End Sites Terminus plugin to:

• Create a new site on Pantheon for the CMS backend of your choice.
• Optionally install your CMS.
• Create a frontend codebase that sources data from your newly created CMS project. This codebase will be automatically configured for local development, and can later be deployed to Pantheon using the import repository workflow.

Before you continue, make sure you have:

• Installed Terminus
• Installed Node.js
• Created a Machine Token

1. Open your terminal and run the command below to install the Terminus Decoupled Kit plugin.

   terminus self:plugin:install pantheon-systems/terminus-decoupled-kit-plugin

   • You should see a message, such as Installed pantheon-systems/terminus-decoupled-kit-plugin

2. Run terminus decoupled-kit:create, updating $SITE-NAME and $LABEL with your own information, to create your project:

   terminus decoupled-kit:create $SITE-NAME $LABEL

   • Additional optional commands:

     • --org[=ORG]: Organization name, label, or ID.
     • --region[=REGION]: The region in which you want to create your site. Refer to the Pantheon regions documentation for more information.
     • --cms[=CMS]: This selects the CMS you want to use. Current supported CMS options are: drupal and wordpress.
     • --install-cms[=INSTALL-CMS]: This instructs the plugin to install your CMS or not. The default value is true. You can set this value to false if you do not want to install a CMS for your project.

3. When prompted, select the CMS you want to use. This option does not appear if you used the optional --cms[=CMS] command. The options should look similar to:

   Choose your CMS back-end:
   [0] Drupal-10
   [1] Drupal-9
   [2] WordPress

   • CMS installation will take several minutes. You should see a message similar to the following example to let you know your project is deploying:

     Creating a new site...
     [notice] Deploying CMS...

4. Enter your password when prompted and enter y to proceed:

   Now let's create your front-end project...
   [Exec] Running npm init pantheon-decoupled-kit@canary -- --cmsType d10 --cmsEndpoint=https://dev-donnerstag.pantheonsite.io
   Need to install the following packages:
   [email protected]
   Ok to proceed? (y)

5. Select the framework generator you want to use:

   Which generator(s) would you like to run? (Press <space> to select, <a> to toggle all, <i> to
   invert selection, and <enter> to proceed)
   ◯ next-drupal
   ◯ next-drupal-umami-addon
   ◯ tailwindcss-addon
   ◯ next-drupal-search-api-addon

6. Enter a name for your project:

   What is the name of your project?

7. Enter the location where you want your output to go. For example, /Users/anitapantheon/anita-site/anita-portfolio:

   Where should the output go?

8. Select if you want to include additional frameworks, such as Tailwind CSS:

   Would you like to include tailwindcss? (Y/n) selected y

9. Select if you want to continue with your selected changes. You will see a list of the changes you selected.

   Listing changes for /Users/anitapantheon/anitasite/anita-portfolio/.env.development.local:
   
   - BACKEND_URL=https://dev-anita-portfolio.pantheonsite.io
   - CLIENT_ID=
   - CLIENT_SECRET=
   - PREVIEW_SECRET=
   - #DEBUG_MODE=true
   ? About to overwrite /Users/anitapantheon/anitasite/anita-portfolio/.env.development.local with
   the changes listed above.
   Would you like to continue? (Use arrow keys)
   yes
   skip
   yes to all
   abort

   If you select yes to all, you'll receive a message similar to:

   Your project was generated with:
   next-drupal
   cd into /Users/anitapantheon/anitasite/anita-portfolio to start developing!
   (node:53117) ExperimentalWarning: Importing JSON modules is an experimental feature and might change at any time
   Goodbye.
   [Exec] Done in 07:44
   [notice] Next steps: import your repository to create a Front-End Site https://docs.pantheon.io/guides/decoupled/no-starter-kit/import-repo
   Your Decoupled Kit project has been created!

   • You can see this backend project in your Pantheon account. Go to your Pantheon dashboard and select Sites. You will see your backend project listed with the label name you entered in the steps above.

10. Import your repository to create the frontend of your Pantheon Front-End Site.

Create with Build Tools

Prerequisites

• Composer (required for CMS backends): Install Composer

• Generate a machine token and authenticate into Terminus

• Install Terminus (3.0.0 or above required)

• Install and confirm Terminus plugins:

  1. Install the Terminus Build Tools and Secrets plugins:

     terminus self:plugin:install terminus-build-tools-plugin terminus-secrets-plugin

  2. Reload the Terminus plugins, clear Composer cache, and validate that the plugins are installed:

     terminus self:plugin:reload && composer clear-cache && terminus self:plugin:list

Build Tools 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.

    Use terminus org:list to list which orgs are available.

    This can also be omitted if the site is not part of an org.

  • Build Tools should prompt you for the credentials required to create these assets. While GitHub and CircleCI are the defaults, other providers are supported as well. Refer to available services for more information.

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

   • This command will create:

     • A Pantheon site
     • A GitHub repository
     • A CircleCI test configuration

2. Refer to Commands available as part of the Build Tools pluginfor additional options for repository or CI providers.

Known Issues with Build Tools

If you encounter errors during the installation process, please check if you have the terminus-power-tools plugin installed. If you do, run the following command to remove it and go through installation again:

terminus self:plugin:uninstall terminus-power-tools

Additional Options

Use Other Git Hosts or CI Services

Terminus Build Tools supports other Git hosts and CI services.

For example, to use GitHub actions as your CI service, you can add the --ci=githubactions flag to your terminus build:project:create command.

Other possible values are:

• circleci
• gitlab-pipelines
• bitbucket-pipelines

Refer to the available services section of the build tools documentation for more information.

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

Update to Drupal 10

Follow the following steps to update a Decoupled Drupal Composer Managed site to Drupal 10.

1. Clone the backend site repository.

2. Update to PHP 8.1 or greater if you have not already done so. Edit pantheon.yml and add the following with your chosen version of PHP:

   pantheon.yml

   php_version: 8.1

3. 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"

4. Push the changes up to Pantheon:

   git push origin master

5. Run database updates if you are updating an existing Drupal install. 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. This would look something like https://dev-my-decoupled-backend.pantheonsite.io/update.php.