The treacherous journey from Pantheon to localhost

We entered into a Drupal project that had been going on for a while. It was a live site hosted on Pantheon, and I was suddenly in charge of maintaining and improving it.

I wanted to document the steps it took to get the site working locally in WAMP, because it was a very long and confusing process. Pantheon is super weird if you've been working with a normal XAMP stack your whole life.

If you are looking to work on a Pantheon Drupal site locally, then this Protip is for you.

Let's Git Started

Sorry about that.

So, the first thing you need is Git knowledge. Your Pantheon Drupal site's code resides within a Git repository, and Pantheon will give you the info you need to clone it locally. Pantheon also allows you to download a copy of the database so you can import it into your localhost phpMyAdmin that comes with WAMP or whatever MySQL server that you use. Easy enough, right?

settings.php

Well, the first problem is going to be with the settings.php file located in your newly-cloned Drupal folder... Let's say this folder is called mysite. So the settings.php file would then be mysite/sites/default/settings.php.

Pantheon has a custom database configuration built into the settings.php file so that they can load-balance your site's databases automagically. And now that your site is on localhost, this Pantheon database magic no longer works, so we need to add in some code to point your Drupal site to your local MySQL server. Put this code in settings.php somewhere before the line that says * Access control for update.php script.. Make sure this code is not commented out, as several nearby code blocks are.

if (!isset($_SERVER['PANTHEON_ENVIRONMENT']) ) {
  $databases['default']['default'] = array(
    'driver' => 'mysql',
    'database' => 'mysite_dev',
    'username' => 'root',
    'password' => '',
    'host' => 'localhost',
    'port' => '',
    'prefix' => '',
  );
}

This if statement checks to see if Pantheon's environment variable (read: signature) exists on your server. If it does not, the if statement proceeds by connecting to your local MySQL server. Be sure to replace the database, username, password, and host with the credentials to your local MySQL server. Also be sure that you imported that database you downloaded from Pantheon into the correct database locally.

Once that's taken care of, we only have a few more things to do in settings.php before we can move on with our lives.

Find the line that says $cookie_domain = '.mysite.com'; Hint: it will say your domain instead of "mysite".

Change .mysite.com to .mysite.local. Note the preceding period.

Next, find the line that says extract(json_decode($_SERVER['PRESSFLOW_SETTINGS'], TRUE));. It's near the bottom of the file.

Change that line to this:

if (isset($_SERVER['PANTHEON_ENVIRONMENT']) ){
  extract(json_decode($_SERVER['PRESSFLOW_SETTINGS'], TRUE));
}

This checks for the Pantheon environment variable once again to see if Pantheon is available. If it is, it executes the extract command. If it isn't (which is the case locally) it ignores the extract command. We are doing this because the extract command will cause an error, but we don't want to get rid of it completely, just in case. If you are brave 'n stuff, just delete that line, but be sure not to commit your changes to settings.php.

This concludes the changes to settings.php, but we aren't done yet.

hosts

You'll need to create records in your hosts file to point mysite.local to your localhost.

Protip: MAKE A BACKUP OF THE HOSTS FILE. DO NOT CHANGE THE LINE ENDINGS OF THE HOSTS FILE. Sublime Text did this to me once and it took me a few hours to figure out why my MAMP server was completely broken. Depending on whether you are on Windows or OS X, your hosts file is supposed to have the corresponding line ending type. It's a good idea to create a copy of the hosts file before you edit it, just in case.

Find the hosts file on Windows by opening up C:\Windows\System32\drivers\etc\hosts (on a Mac it's located at /private/etc/hosts ) in a text editor with administrative privileges. Add a line like this at the end of the file:

127.0.0.1   mysite.local

Save the file and close 'er up. Now, in case you don't know why you had to do that, here's the short version. The hosts file is checked when you try to reach a domain from your computer, and your computer will follow whatever IP address is listed for that domain, regardless of what the rest of the world thinks. We made it so that mysite.local will refer to your local machine instead of trying to find a real website called mysite.local somewhere on the internet (which doesn't exist and would yield an error.)

httpd-vhosts.conf

Now, create Virtual host record in your XAMP config for mysite.local and point it to your mysite Drupal folder. This little snippet goes at the end of your C:\Users\myself\wamp\bin\apache\Apache2.2.21\conf\extra\httpd-vhosts.conf file:

<VirtualHost *:80>
    ServerAdmin me@myemail.com
    DocumentRoot "C:\Users\myself\wamp\www\mysite"
    ServerName mysite.local
    ServerAlias www.mysite.local
    ErrorLog "logs/mysite/error_log"
    CustomLog "logs/mysite/access_log" common
</VirtualHost>

Of course, some of the paths might be different. You might even have to use forward slashes instead of backslashes if you're on a Mac / MAMP server. And the path to httpd-vhosts.conf might be different too. You might have a different version of Apache or something, it's okay. Just stay cool and look for similar folders, you'll be fine.

After you update your virtual hosts file, restart WAMP or whatever web server you are using.

Alright, so we've nearly configured everything that needs to be configured, but there's one last thing, and there's only one or two more steps to go.

Clear your caches

Open up a browser — and reopen your browser if you had it open already — and go to mysite.local. It should come up. Log in and clear the caches under mysite.local/admin/config/development/performance.

Now that you've done that, you should be up and running!... unless... you have the Domain Access module installed. Then you have do one more thing.

Domain Access database table

If you have the Domain Access module installed and your localhost site isn't working, go to phpMyAdmin (or whatever MySQL thingy you are using) to edit the database. Go to the domain table. Look for the record that has mysite.com under the subdomain column. You'll need to change that to mysite.local. You'll also need to change the scheme column to be http instead of https because you probably don't have https configured on your localhost environment. If it's already http then don't worry about changing that. But you still need to make sure the subdomain says mysite.local.

Darn that Domain Access module, making things more complicated! Well, at least your site will work now.

Some things to remember

Don't commit your settings.php file like it is. If you want to commit it, you'll need to modify the line with $cookie_domain line to check for the Pantheon environment variable and change the $cookie_domain variable depending on whether you're on Pantheon or not. That will allow you to commit this file and keep both your local and remote installations working.

When you push from local to Pantheon, it deploys your latest commit to the Dev environment. That's a good thing to remember.

Anyways, I sure hope that this helps someone out. Thanks for reading.

/**
 * Load local development override configuration, if available.
 *
 * Use settings.local.php to override variables on secondary (staging,
 * development, etc) installations of this site. Typically used to disable
 * caching, JavaScript/CSS compression, re-routing of outgoing e-mails, and
 * other things that should not happen on development and testing sites.
 *
 * Keep this code block at the end of this file to take full effect.
 */
if (!defined('PANTHEON_ENVIRONMENT')) {
        $conf_path = conf_path();
        if (file_exists(DRUPAL_ROOT . '/' . $conf_path . '/settings.local.php')) {
          include DRUPAL_ROOT . '/' . $conf_path . '/settings.local.php';
        }
}

<?php
$databases = array (
  'default' =>
  array (
    'default' =>
    array (
      'database' => 'some_db',
      'username' => 'some_user',
      'password' => 'some_pw',
      'host' => '127.0.0.1',
      'port' => '',
      'driver' => 'mysql',
      'prefix' => '',
    ),
  ),
);

// Other stuff useful during development

// Disable cache
$conf['cache'] = 0;

// Disable css and javascript aggregation by default
$conf['preprocess_css'] = 0;
$conf['preprocess_js'] = 0;

$base_url = 'http://site.dev:8888';