Skip to main content
Log inGet free account
Last Reviewed: March 10, 2022

Local Development Configuration

Configure your machine for local development with Pantheon.

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

This section provides information on how to configure your machine for successful local development with your Pantheon site.

Before You Begin

Export Your Variables

This section uses several commands that use the temporary command line alias, $SITE, to make entering command examples easier. Export your variables and clear your site environment cache before you configure your local development setup.

  1. Set the temporary variable $SITE in your terminal session to match the name of your site. Replace anita-drupal with your site's name in this example:

    export SITE=anita-drupal && echo "New alias set as $SITE"
    How to Use Terminus to Find the Site Name

    Use terminus site:list for a list of sites you have access to:

    terminus site:list
--------------------------- --------------------- ------------- ----------------------------------- -------------------- --------------------- ------------- ------------
Name                        ID                    Plan          Framework          Region           Owner                Created               Memberships   Is Frozen?
--------------------------- --------------------- ------------- ------------------- ---------------- -------------------- --------------------- ------------- ------------
anita-drupal                abdc80ce-286c-1234-   Sandbox       drupal8             Canada           3374708c-987e-1234   2020-12-15 19:40:42   d3ecc20c-395a falseanita-wordpres              abdc9954-fab2-1234-   Sandbox       wordpress           United States    c96ddb25-336a-1234   2020-09-02 07:18:51   d3ecc20c-395a false

    The site name is listed under Name. In this example, the site name is anita-drupal.

  2. Export the environment as a variable:

    export ENV=dev

  3. Run the command below to clear the target site environment's cache. This can also be done from the Pantheon Dashboard or from the application itself.

    terminus env:clear-cache $SITE.$ENV

Transfer Your Code

Follow the steps below to get a clone of your Pantheon code on your local computer.

  1. Log in to Pantheon and go to the Site Dashboard.

  2. Locate the git clone command at the top of the development panel and copy and paste it into your terminal.

    It should look similar to this:

    Example of Git Clone repo for command line: `git clone ssh://codeserver.dev.0e1f236a-ec36-4143-a900-73a92a344`

  3. Go to where you want the code to reside in your local environment.

    Git automatically creates a directory as part of the clone.

  4. Run the clone command you copied:

    git clone ssh://[email protected]:2222/~/repository.git my-site

    Git fetches the data if everything worked correctly:

    Cloning into 'anita-wordpress'...
The authenticity of host '[codeserver.dev.....drush.in]:2222 ([173.255.119.72]:2222)' can't be established.
RSA key fingerprint is SHA256:yPEkh1Amd9WFBSP5syXD5rhUByTjaKBxQnlb5CahZZE.
Are you sure you want to continue connecting (yes/no/[fingerprint])? yes
Warning: Permanently added '[codeserver.dev.....drush.in]:2222,[173.255.119.72]:2222' (RSA) to the list of known hosts.
remote: Counting objects: 20503, done.
remote: Compressing objects: 100% (8184/8184), done.
remote: Total 20503 (delta 12802), reused 19671 (delta 11982)
Receiving objects: 100% (20503/20503), 46.65 MiB | 15.16 MiB/s, done.
Resolving deltas: 100% (12802/12802), done.
    • Check your SSH key setup if you run into permission problems.
    • Check your network to confirm that you have a current version of Git if the clone starts but can't complete.

Transfer Your Database

Via Dashboard

  1. Navigate to the Site Dashboard.

  2. Select Database / Files, select Export, and then select Export Database to create an on-demand backup.

  3. Select Backups, select Backup Log, and then select Database download link to download the backup.

  4. Import the database into your local environment with your MySQL client:

    gunzip < database.sql.gz | mysql -uUSER -pPASSWORD DATABASENAME
    Note

    Replace database.sql.gz with the name of the database archive downloaded from Pantheon.

Via Terminus

  1. Create and get the database with Terminus commands:

    terminus backup:create $SITE.$ENV --element=db
terminus backup:get $SITE.$ENV --element=db

  2. Run the command below to import the archive into your local MySQL database:

    gunzip < database.sql.gz | mysql -uUSER -pPASSWORD DATABASENAME

Transfer Your Files

Refer to SFTP and Rsync on Pantheon for an overview of ways to transfer files.

Via Terminus

  1. Run the Terminus commands below to create and get a backup of the site's files:

    terminus backup:create $SITE.$ENV --element=files
terminus backup:get $SITE.$ENV --element=files

  2. Move the resulting backup to the correct directory on your local file system:

    • Drupal: sites/default/files
    • WordPress: wp-content/uploads

Via SFTP CLI

SFTP is a slower method, but easier for some to use:

  1. Click Connection Info to get your SFTP login credentials.

    You will see your connection credentials and a link to connect directly with your preferred client.

  2. Use the terminal to navigate to the correct directory on your local file system:

    • Drupal: sites/default
    • WordPress: wp-content/uploads

  3. Paste the CLI command copied from your Dashboard.

  4. Run get -r * to transfer the files down to your local environment.

Submit Changes to Pantheon

Send the Code

  1. Test your changes, then commit locally and push to Pantheon:

    git commit -am "enter a summary of the changes"

  2. Push the changes:

    git push origin master

Send the Database

  1. Create an archive using the MySQL utility mysqldump:

    mysqldump -uUSERNAME -pPASSWORD DATABASENAME | gzip > database.sql.gz

  2. Open your Pantheon Dashboard and select Database / Files, then select Import to upload and import the file.

Send the Files

Upload files to Drupal Via Drush

Drush and Rsync are the easiest ways to send files for Drupal sites:

drush -r . rsync --temp-dir=../tmp/ @self:sites/default/files/ @pantheon.SITENAME.ENV:%files

Upload Files to WordPress or Drupal Via SFTP

Send files using SFTP:

  1. Copy the SFTP CLI command.

  2. Use the terminal to navigate to the correct directory on your local file system:

    • Drupal: sites/default/files
    • WordPress: wp-content/uploads

  3. Paste the CLI command copied from your Dashboard.

  4. Navigate to the correct remote directory by running cd files

  5. Run put -r ./* to transfer the files.

You can also transfer a single file or a single directory at a time instead of transferring every file, every time.

Local Configuration Files

You must configure database credentials that match your local database to develop locally. Do not manually change these details in your primary configuration file (settings.php or wp-config.php), as this could commit changes to version control and trigger a connection error on Dev when pushing to Pantheon.

Use a local configuration file:

  • Drush: settings.local.php
  • WordPress: wp-config-local.php

Your local configuration file must be excluded from version control and included by settings.php or wp-config.php when found. Your local configuration file won't be found on Pantheon because Git ignores the local configuration file, but it will be applied when you run the site locally.

Pantheon's upstreams detect and include wp-config-local.php (WordPress) and settings.local.php (Drupal 8) for local environment configurations.

This file is ignored by the .gitignore file in WordPress and Drupal 8 so that local configurations do not get pushed to Pantheon. Create the file on your local computer, and manage configurations accordingly.

WordPress wp-config-local.php

Pantheon sites that install WordPress 5.5 include a wp-config-local-sample.php file. Older sites can copy the wp-config-local-sample.php file on GitHub to the same directory as the site's wp-config.php, or create one in that location as shown here.

This can be used as a starting point for wp-config-local.php. Replace the database values with the values from your local environment, and the key/salt values with your unique phrase (generated from WordPress.org).

Drupal settings.local.php

  1. Create the local settings file and add it to .gitignore.

  2. Change to the site's directory and create the file.

  3. Change the first command in this example to fit the site's directory structure:

    cd sites/default
touch settings.local.php

  4. Add the local configuration file to .gitignore:

    .gitignore
    sites/*/settings.local.php

Drupal 7 users must add a reference to the local file from within settings.php:

sites/default/settings.php
/**
 * Drupal 7 only: Include a local settings file if it exists.
 */
$local_settings = dirname(__FILE__) . '/settings.local.php';
if (file_exists($local_settings)) {
  include $local_settings;
}

More Resources