local-development.md

title	description	tags	categories
Local Development	Suggestions and solutions for working locally on your Pantheon Drupal or WordPress site.	local

While Pantheon provides several options for on-server development, local development has a number of advantages, especially if continuous Internet access is a concern.

[Agency DevOps Training](https://pantheon.io/agencies/learn-pantheon?docs){.external}

Dev/Test/Live, Multidev, local development, and more! Learn how Pantheon's DevOps training can accelerate your workflow.

Pantheon cannot troubleshoot or support local development solutions; however, we can provide some suggestions and known working solutions. For large teams/sites, we recommend using Multidev instead of local development.

Before You Begin

Be sure you have:

• A local stack capable of running Drupal or WordPress. Lando{.external} integrates with the Pantheon platform. Tools such as MAMP, WAMP, and XAMPP all work.
  • Pantheon uses a particular architecture to maximize performance and availability, but it's possible to run the same code on a variety of different configurations. As long as the solution supports a minimum of PHP 5.3 and MySQL, you should be fine.
  • Ensure that your local stack's PHP version matches the PHP version set for the target site on Pantheon.
• Git client for tracking code changes
• SFTP client, such as FileZilla, for transferring files OR rsync
• Terminus
• Drush (optional)

To save time, clear the target site environment's cache. This can be done from the Pantheon Dashboard, from the application itself, or by running the following Terminus command:

terminus env:clear-cache <site>.<env>

There are three parts to any dynamic website:

1. Code (The application, modules or plugins, and themes)
2. Database (content)
3. Files (user uploaded or application generated)

You will need to transfer each one from Pantheon to your local environment.

Get the Code

The first step is to get a git clone of your code from Pantheon to your local computer.

1. Go to Your Site Dashboard, and log in to Pantheon and load the Dashboard for the site you want to work on.

2. At the top of the development panel, look for the git clone command and copy and paste it in your terminal. It will look something like this:

   
   

3. On your local environment, go to where you want the code to reside. Git will create a directory as part of the clone, so you don't need to create one. Run the command you copied in step 2:

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

   If everything worked correctly, you will see Git fetching the data:

   
   

   If you run into permission problems, check your SSH key setup. If the clone starts but can't complete, check your network to see if you have a current version of Git.

Get the Database

Via Dashboard

From within the Site Dashboard:

1. Create an on-demand backup by selecting Database / Files > Export > Export Database.

2. Download the scheduled or on-demand backup by selecting Backups > Backup Log > Database download link.

3. Import the database into your local environment using a 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. Import the archive into your local MySQL database using the following command:

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

Get the Files

For an overview of ways to transfer files, see SFTP and rsync on Pantheon.

Via Terminus

Run the following Terminus commands:

terminus backup:create <site>.<env> --element=files
terminus backup:get <site>.<env> --element=files

This will create and get a backup of the site's files.

Via SFTP CLI

SFTP is slower, but easier for some to use:

• Get your SFTP login credentials by clicking Connection Info. You will see your connection credentials and a link to connect directly with your preferred client.
• From the terminal, navigate to the proper directory on your local file system:
  • Drupal: sites/default
  • WordPress: wp-content/uploads
• Paste the CLI command copied from your Dashboard.
• Run get -r * to transfer the files down to your local environment.

Submit Changes to Pantheon

Send the Code

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

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

Next, push the changes:

git push origin master

Send the Database

Create an archive using the MySQL utility mysqldump:

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

Upload and import the file by going to your Pantheon Dashboard and selecting Database / Files > Import.

Send the Files

Drupal: Via Drush

Drush and rsync is by far the easiest way to send files for Drupal sites:

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

WordPress or Drupal: Via SFTP

Send files using SFTP:

• Copy the SFTP CLI command
• From terminal, navigate to the proper directory on your local file system:
  • Drupal: sites/default/files
  • WordPress: wp-content/uploads
• Paste the CLI command copied from your Dashboard
• Navigate to the correct remote directory by running cd files
• Run put -r ./* to transfer the files up

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'll need to configure database credentials matching your local database to develop locally. You don't want to manually change these details in your primary configuration file (e.g. settings.php or wp-config.php) because you could easily commit that change to version control and trigger a connection error on Dev when pushing to Pantheon.

Instead, we recommend using a local configuration file (e.g. settings.local.php or wp-config-local.php) that is excluded from version control and included by settings.php or wp-config.php when found. Since the local configuration file is ignored by git, it won't be found on Pantheon but it will be applied when you run the site locally.

Drupal 8 and WordPress

Pantheon's upstreams will 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. Simply create the file on your local computer, and manage configurations accordingly.

Drupal 7

1. Drupal 7 users will need to create a local settings file (e.g.settings.local.php) and include it within their settings.php file:

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

2. You will also need to exclude the local configuration file from git, by adding the following to .gitignore:

   sites/*/settings.local.php