Local Development
Suggestions and solutions for working locally on your Pantheon Drupal or WordPress site.
Discuss in our Forum Discuss in SlackWhile Pantheon provides several options for on-server development, local development has a number of advantages, especially if continuous Internet access is a concern.
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.
If you encounter any issues, visit the Lando GitHub repository.
Before You Begin
There are three parts to any dynamic website:
Code: The application, modules or plugins, and themes.
Database: The content.
Files: User uploaded or application generated.
You will need to transfer each file from Pantheon to your local environment.
Be sure you have:
- A local stack capable of running Drupal or WordPress. Lando integrates with the Pantheon platform. Tools such as MAMP, WAMP, and XAMPP are compatible.
- 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 or IDE, such as WinSCP or Visual Studio Code, for transferring files OR Rsync
- Terminus
- Drush (optional)
Export Variables
Set the temporary variable $SITE
in your terminal session to match the name of your site.
This doc uses several commands that use the temporary command line alias, $SITE
, to make entering command examples easier. Refer to the steps further in this doc to see which sites should be aliased (it may be more than one), then replace anita-drupal
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
.
Export the environment as a variable as well:
export ENV=dev
Clear Site Environment Cache
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
Get the Code
The first step is to get a git clone
of your code from Pantheon on your local computer.
Log in to Pantheon > Open the Site Dashboard.
Locate the
git clone
command at the top of the development panel > Copy and paste it into your terminal.It will look similar to this:
Go to where you want the code to reside in your local environment.
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://codeserver.dev.xxx@codeserver.dev.xxx.drush.in:2222/~/repository.git my-site
If everything worked correctly, you will see Git fetching the data:
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.
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
Navigate to the Site Dashboard.
Select Database / Files, select Export, and then select Export Database to create an on-demand backup.
Select Backups, select Backup Log, and then select Database download link to download the backup.
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
Create and get the database with Terminus commands:
terminus backup:create $SITE.$ENV --element=db terminus backup:get $SITE.$ENV --element=db
Run the command below to import the archive into your local MySQL database:
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.
Move the resulting backup to the correct directory on your local file system:
- Drupal:
sites/default/files
- WordPress:
wp-content/uploads
- Drupal:
Via SFTP CLI
SFTP is slower, but easier for some to use:
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.
Use the terminal to navigate to the correct directory on your local file system:
- Drupal:
sites/default
- WordPress:
wp-content/uploads
- Drupal:
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"
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
Open your Pantheon Dashboard and select Database / Files > 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:
Use the terminal to navigate to the correct directory on your local file system:
- Drupal:
sites/default/files
- WordPress:
wp-content/uploads
- Drupal:
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.
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. Do not manually change these details in your primary configuration file (e.g. 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.
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.
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.
WordPress wp-config-local.php
Pantheon sites that install WordPress 5.5 include a wp-config-local-sample.php
file. Older sites can copy 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.
The following 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).
Full text of wp-config-local-sample.php
<?php
/**
* This is a sample config for local development. wp-config.php will
* load this file if you're not in a Pantheon environment. Simply edit/copy
* as needed and rename to wp-config-local.php.
*
* Be sure to replace YOUR LOCAL DOMAIN below too.
*/
define( 'DB_NAME', 'database_name' );
define( 'DB_USER', 'database_username' );
define( 'DB_PASSWORD', 'database_password' );
define( 'DB_HOST', 'database_host' );
define( 'DB_CHARSET', 'utf8' );
define( 'DB_COLLATE', '' );
define( 'AUTH_KEY', 'put your unique phrase here' );
define( 'SECURE_AUTH_KEY', 'put your unique phrase here' );
define( 'LOGGED_IN_KEY', 'put your unique phrase here' );
define( 'NONCE_KEY', 'put your unique phrase here' );
define( 'AUTH_SALT', 'put your unique phrase here' );
define( 'SECURE_AUTH_SALT', 'put your unique phrase here' );
define( 'LOGGED_IN_SALT', 'put your unique phrase here' );
define( 'NONCE_SALT', 'put your unique phrase here' );
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', true );
define( 'WP_HOME', '<YOUR LOCAL DOMAIN>' );
define( 'WP_SITEURL', '<YOUR LOCAL DOMAIN>' );
define( 'WP_AUTO_UPDATE_CORE', false );
Drupal settings.local.php
Create the local settings file and add it to
.gitignore
.Change to the site's directory and create the file.
Change the first command in this example to fit the site's directory structure:
cd sites/default touch settings.local.php
Add the local configuration file to
.gitignore
:.gitignoresites/*/settings.local.php
Note that Drupal 7 users need to add a reference to the local file from within 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;
}