Using Sourcetree and Acquia Dev Desktop with Drupal

This is part two of a three-part tutorial where you will learn how to use a Git GUI with Drupal to make some theme tweaks on a live site. Part one of this tutorial starts here.

Overall we are looking to cover:

• Setting up a local stack (in this case Acquia Dev Desktop 2).
• Creating an SSH key in Terminal on the Mac
• Cloning an existing Drupal site repository using Sourcetree
• Downloading and connecting to your live site's Drupal database dump file
• Applying theme changes to the cloned site with CSS
• Merging and pushing your changes to live with Sourcetree

Clone the repository you require

First you need to use a tool that can connect via SSH to the repository you need, and then clone (download) everything you require to start making changes. This tool should also be able to push (effectively uploading) your changes back to the repository so that they can be merged with the ‘master branch’  which you cloned.

I’ll be using SourceTree for this. You can download and install SourceTree for free here http://www.sourcetreeapp.com/

Once installed, feel free to also add your GitHub account while installing, if your account contains repos you want to work on locally.

• In SourceTree, select [+ New Repository], then choose [Clone from URL]
• In the cloud hosting environment, navigate to the development tab/panel for the repository you are wanting to clone
• From here, access the URL and copy it using cmd+c

It will look something like this:

ssh://git@repo.ac/2ccbf42ks55801a498c984hdetytsb7fhnsk4dc.git

When you paste the URL into SourceTree, in the Source URL, click on the field for Destination Path. From here, you will probably be asked to enter the pass phrase you entered when generating the SSH key.

Change the Destination Path to match where you want it cloned. This path should ideally be inside the directory you chose for local sites to be stored when you installed your stack (in my case Acquia Dev Desktop 2), and the name of the folder for this clone to something a little more human-readable, for your sake.

Change the Name field to the exact same as the folder you have renamed, for consistency.

Also, in the [Advanced Options] drop-down, check that the ‘Checkout branch’ is the branch you want to be cloning. By default, it probably will be, but better safe than sorry. In our Git workflow this is usually the Master branch.

Enter the pass phrase you confirmed when generating the SSH key pairs earlier, and you should be good to go ahead with Cloning. Click [Clone].

In SourceTree press GitFlow in the top-right of the main UI, to check that the branches and prefixes are ok.

Connect your cloned repo to your local stack

Finally, so that you can see the changes you make locally without pushing (uploading) them to a hosting environment, you will need to connect your cloned repository to the stack you installed earlier.

Open up your stack (in my case Acquia Dev Desktop 2). The default welcome window provides an option to ‘Start with an existing Drupal site located on my computer’. Click this option and you will get the following options (see below).

I selected the following ‘Import local Drupal site’ options:

For the top option ‘Local codebase folder’, I chose the root folder for the repo I had cloned. Everything else pretty much populates itself, although I made the following tweaks.

For this particular site, the hosting environment is using PHP 5.4+ but not yet fully tested with PHP 5.5. Therefore I changed the PHP version accordingly.

The database dump file was renamed simply to be more human-readable, so I knew what it was in future. I then chose this database dump file in the corresponding field on Acquia Dev Desktop.

I downloaded a copy of the live database from the live hosting panel of the repository. In our cloud hosting options, when the database dump is selected for downloading, a message notification appears when the Amazon S3 link is ready for a manual click and download.

Ignore local compressed CSS and JS files

If you don’t want CSS/JS compression turned on, which you won’t when making front-end changes, you may need to turn it off on the live site before exporting the database (remember to turn it back on in the live site afterwards). There is also a way round this.

To avoid needing to turn off the CSS and JavaScript file compression settings in Drupal’s performance options on the live site before dumping the database for local use, simply add the following two lines of code into (preferably the bottom of) your settings.php file in the root of your cloned repository’s ../sites/ directory:

$conf['preprocess_css'] = FALSE;
$conf['preprocess_js'] = FALSE;

Start locally testing your cloned Drupal site

Click on the Local site link provided by your stack. The link for me is http://sitename.dd:8083

That should open up your default web browser and display the homepage of your site. If it doesn’t, you may have one of a number of things to do.

Make sure Drupal exists in your local repo

The Amazon cloud hosting setup we use enables fast, streamlined security updates to Drupal core. This means that the actual Drupal installation is in a different place to the rest of the repository. Which means we also need to include an extracted Drupal installation in the directory where we have the cloned repository.

• Look in the repository on your hosting environment and check what version of Drupal you need to get this working
• Download this exact same version of Drupal from Drupal.org and extract it in Finder (on the Mac)
• Do not copy the ‘sites’ folder
• Don't copy the .htaccess file, robots.txt file or the .gitignore file
• Copy everything else from within this extracted directory to inside of the cloned repo folder
• Try your stack’s Local site link again, and you should see a local working version of the site’s homepage.

Stuff's still going wrong? Ok next up...

Make sure you have an .htaccess file

It this point, you may well find that if you start clicking around to navigate to another page, it will display a page not found 404 error. This is because there is currently no .htaccess in the root of your local repo.

The simple solution is to copy the default .htaccess file from the extracted Drupal installation folder (which was downloaded off Drupal.org) into the root of your local repo.

We didn’t do this earlier as a precaution to prevent overwriting an .htaccess file that already does exist in your local repo root directory.

Connect Drupal to your local MySQL database

You may also need to manually connect your MySQL database to the site using a separate settings PHP file.

For me, using Acquia Dev Desktop 2 with an already slightly customised Drupal settings.php file that we use, (in order to deployment clean on dev, staging and live), I had to create a local.settings.php file for my local repo.

This file was created in my local repo in ../sites/default/ and I added the following code, where dbname is the name you gave your database dump when importing the db dump into the stack.

<?php
$databases['default']['default'] = array(
   'driver' => 'mysql',
   'database' => ‘dbname’,
   'username' => 'drupaluser',
   'password' => '',
   'host' => '127.0.0.1',
   'port' => 33067
);

Password will be nothing by default, and the username will be drupaluser by default.

Please make sure that you use your correct MySQL port in this code (33067 in my case). You can check this in Acquia Dev Desktop 2 by going to:

Preferences > Settings > Ports (and look at the number for the MySQL port)

Add files and images from the files directory

In my cloned repo, there is one last step to get everything working properly. Image files are missing, and I need them to check that the front-end changes I am about to make are working ok before pushing them back up, ultimately to the master branch (covered in part three - merging and pushing your local changes to live with SourceTree).

In the hosting environment’s control panel (for us this is at http://console.ac), I’ll navigate to the Content Management tab within the Live panel for the repo I have cloned. From here I can click [Download] in the FileSystem column. This initiates the download of all files that can then be moved into the local directory. For a Drupal site, which this is, the path will be something like:

Users/yourname/LocalDev/your-cloned-site-folder/sites/default/files/

That should correct any issues you may have had with missing images on your local site. Sometimes you may need to restart your stack and of course refresh the browser to get this working again.

High five! You really are now a level 1 Drupal ninja guru warrior. Now you can make those CSS changes, or whatever you need to change. If you are just following along to start learning a Git workflow with Drupal, make some slight changes to few CSS files, so that you have something to merge for part three.

Next up: How to push and merge your changes to the live server. You should now have pretty much everything set up for the process of pushing your changes and merging them with the master branch to deploy them to the live hosting environment.

Hopefully you got some good tips in this guide. Share it with the world! Also, feel free to tweet me or @curveagency if you have any questions.