Skip to main content
Log inGet free account

Create a Drupal Site From the Command Line Using Terminus and Drush

Learn how to manage configuration between Pantheon environments using the command line.

Discuss in Slack
Edit this page on GitHub Report an issue with this doc

Drush is a tool for working with Drupal from the command line. Terminus allows you to use the command line to do everything you can do in Pantheon's browser-based dashboard. You can also run Drush commands directly from Terminus, making it a single solution for command line development on Pantheon.

This section walks you through using Drush and Terminus in the command line to create a new Drupal site and move configurations between Pantheon environments.

Before You Begin

Be sure that you:

  • Are familiar with your operating system's command line.
  • Are using a Unix-based system (Linux or Mac OS X). Windows commands may vary slightly.
  • Have created a Pantheon account. Pantheon accounts are always free for development.
  • Have an SSH key generated, added to your Pantheon dashboard, and loaded in to your local SSH agent.
  • You have Composer, the package manager for PHP, installed on your machine.

Install and Authenticate Terminus

Terminus provides advanced interaction with the platform and allows us to run Drush commands remotely. Terminus also opens the door to automating parts of your workflow by combining multiple operations. Refer to the Terminus Guide for more information.

  1. Install Terminus.

  2. Go to your Personal Settings, select Account and Security, and then select Machine Tokens to generate a Machine Token.

  3. Use the Machine Token to authenticate Terminus:

    terminus auth:login --machine-token=‹machine-token›

  4. Verify your session after installation:

    terminus site:list

Your installation and authentication were successful if your Pantheon site is on the list.

Create Your Site and Initialize Environments

Note

The next few sections use the example variables my-site and "My D9 Site" as the site name and label. Make sure you replace each instance, as well as other variables, with your desired values.

  1. Create a new Drupal site on Pantheon:

    terminus site:create my-site "My Site" "drupal-composer-managed"

  • You can add the --org option to the command above and pass the Workspace name, label, or ID if you want to associate this site with an Workspace.

  • Use the site:org:add command to associate an existing site with an Workspace.

  1. Open your new Site Dashboard in a browser:

    terminus dashboard:view my-site

    Keep this window open while you continue reading so you can see the changes you are making in Terminus appear almost immediately in your Site Dashboard.

  2. Use the Drush site-install command to install the latest version of Drupal on the Dev environment:

    terminus drush my-site.dev -- site-install -y

  1. Use the password included in the output of that command to sign in to the site with your browser, or use this command to get a one-time login link:

    terminus drush  my-site.dev  -- user-login

  2. Create the Test environment:

    terminus env:deploy my-site.test

  3. Create the Live environment:

    terminus env:deploy my-site.live

Export the Site Name as a Variable

You can now replace my-site in every command, so that you don't have to type it every time.

  1. Set the site name to a variable so you can copy and paste the remainder of your commands instead of typing the site name:

    export TERMINUS_SITE=my-site

    This sets an environment variable named $TERMINUS_SITE to steve-new-site. The variable name is replaced in the executed command with the value whenever you use the variable name.

  2. Test this by echoing your variable:

    echo $TERMINUS_SITE

    You can now copy and paste the remainder of these commands without replacing the site name because they use the $TERMINUS_SITE variable.

  3. Run the command below to get the connection information for the Dev environment:

    terminus connection:info $TERMINUS_SITE.dev

Install Terminus Composer plugin

Run the command below to install the Terminus Composer plugin.

terminus plugin:install "pantheon-systems/terminus-composer-plugin"

Install Drupal Modules

We recommend that you use Integrated Composer to install and manage your modules. Integrated Composer is a Pantheon platform feature that extends Composer functionality to Drupal's core files, and treats them as a managed dependency. Integrated Composer lets you perform one-click updates from the Dashboard for upstream updates and Composer dependencies.

You can also manage all modules with Composer, or with Pantheon's Terminus Composer plugin, which runs Composer commands in your development environment.

We recommend that you download and enable modules from the devel package. These modules are helpful while a site is under construction. You can read more about this package of modules on drupal.org.

You may want to remove these modules after you launch your site, or use more advanced configuration management techniques to keep the module on in the Dev environment and off in Test and Live environments. You can have the modules installed in all three environments for this exercise on a Sandbox site.

  1. Download and install the latest stable release of the devel package from drupal.org via Composer:

    terminus composer $TERMINUS_SITE.dev -- require drupal/devel

  2. Review the file changes:

    terminus env:diffstat $TERMINUS_SITE.dev

  3. Commit your changes to the Dev environment:

    terminus env:commit  $TERMINUS_SITE.dev --message="Adding devel module"

  4. Enable the modules:

    terminus drush $TERMINUS_SITE.dev -- pm-enable devel devel_generate webprofiler -y

    All of these modules are helpful during active development. Devel Generate is used in this walk-through to make nodes on the Live environment.

  5. Sign in to your Dev environment if you haven't already done so. You will see a footer of helpful development information provided by the webprofiler module you just installed:

    terminus drush $TERMINUS_SITE.dev -- user-login

    The webprofiler toolbar

  6. Export the configuration in the Dev environment:

    terminus drush $TERMINUS_SITE.dev -- config-export -y

  7. Commit the changes:

    terminus env:commit  $TERMINUS_SITE.dev --message="export of config files"

  8. Deploy the changes to the Test environment, and clear the site cache:

    terminus env:deploy $TERMINUS_SITE.test --sync-content --updatedb --note="Deploying exported config to enable modules"
terminus env:clear-cache $TERMINUS_SITE.test
    Note

    The --sync-content option pulls the database and files down from the Live environment. In a real-world scenario, your content editors most likely have added content and files in the Live environment. For thorough testing, you want those updates present on the Test environment with your deployed code. For more information on options for the this command, run terminus env:deploy -h.

  9. Import the yml configuration files now present on the Test environment into the database using the following command:

    terminus drush $TERMINUS_SITE.test -- config-import -y

  10. Sign in to Drupal in the Test environment to see the enabled modules:

    terminus drush $TERMINUS_SITE.test -- user-login

  11. Sign in to Drupal in the Live environment to see that the modules aren't there yet:

    terminus drush $TERMINUS_SITE.live -- user-login

    Now that you are signed in to all three environments you should see the development footer in Dev and Test, but not Live.

  12. Push your code changes to the Live environment, and clear the site cache:

    terminus env:deploy $TERMINUS_SITE.live --updatedb --note="Deploying exported config to enable modules"
terminus env:clear-cache $TERMINUS_SITE.live

  13. Import the configuration on the Live environment:

    terminus drush $TERMINUS_SITE.live -- config-import -y

    You will be able to refresh the Live environment in your browser and see the development footer when this command completes.

Managing Content, Configuration, and Code Across Environments

Drupal configuration information is stored in the database by default and can be exported to yml files. Configuration changes can be deployed to different environments (e.g. Test or Live) after you export to files and commit to Git. These changes can then be imported to the database.

In the lifecycle of managing a site, content editors will add new material to the Live environment. We recommend you move updated content into the Test and Dev environments from time to time to build and test features with fresh material from the Live environment.

Follow the steps below for a demonstration of the typical workflow on Pantheon.

  1. Create content in Live using the generate-content command:

    terminus drush $TERMINUS_SITE.live -- devel-generate-content 25

  2. Copy the database and media files from the Live environment to the Dev environment:

    terminus env:clone-content $TERMINUS_SITE.live dev

  3. Make a configuration change on the Dev environment, such as enabling the glossary that comes with Views module in Drupal core:

    terminus drush $TERMINUS_SITE.dev -- views-enable glossary

  4. Export the configuration change so it can be managed in code:

    terminus drush $TERMINUS_SITE.dev -- config-export -y

  5. Commit your code changes to the Dev environment:

    terminus env:commit $TERMINUS_SITE.dev --message="Enabling glossary View"

  6. Check the Test environment before you deploy to get a deeper understanding of this workflow.

    Visit /glossary and /admin/content in your Test environment. You should see a 404 message for the glossary page and the administrative content list should not contain the articles and pages that were made on Live. You should see something different on both URLs after you deploy our code in the next step.

  7. Deploy code, clear the site cache, and import configuration changes to Test:

    terminus env:deploy $TERMINUS_SITE.test --sync-content --updatedb --note="Deploying glossary View"
terminus env:clear-cache $TERMINUS_SITE.test
terminus drush $TERMINUS_SITE.test -- config-import -y

  8. Check the Test environment and visit /glossary and /admin/content again. You should see both the glossary view and a full list of content on the administrative page.

  9. Deploy to the Live environment, clear the site cache, and import the changes:

    terminus env:deploy $TERMINUS_SITE.live --updatedb --note="Deploying glossary View"
terminus env:clear-cache $TERMINUS_SITE.live
terminus drush $TERMINUS_SITE.live -- config-import -y

    You should be able to see the glossary page (/glossary) with the change to the glossary View deployed and imported on the environment.

The Power of Terminus and Drush

Terminus provides the power to manage most aspects of your Pantheon sites, while tools like Drush (and WP-CLI for WordPress) give you the power to manage the inner workings of your Drupal-powered site. Now, you're ready to take the sandbox site you've setup and explore on your own to see what else is possible.

More Resources