Setting up a Local Development Environment via Acquia Dev Desktop

This is a recommended local development setup, that doesn’t take too long to do and is fairly fast to set up.  We’re assuming you already have Git access and you have your Git repository setup and that you’re at least a little comfortable with server concepts and the command line.

Since it connects directly to Git, it's up to date, and can take advantage of awesome development strategies like Branching, also it allows you to run all your UCSF Drupal 7 multisite sites in one setup!

Setup Dev Desktop

Download and install Acquia Dev Desktop -- you could use another testing server stack, but these instructions are written for this.

Once it is installed, we will change three settings from the stock settings to better suit our environment:

  1. Open the Acquia Dev Desktop Control Panel.
  2. Select Settings... > Port to confirm that your port numbers are Acquia-standard: HTTP = 8082 and MYSQL = 33066.
  3. Select Settings... > Config > then select the link in the PHP section called Edit. An editor opens with the php.ini file.
  4. Find the following settings and make the changes listed:
    post_max_size 256M
    upload_max_filesize 256M
    memory_limit 256M
    apc.shm_size 512M

Connect Acquia to your Git repository

Acquia installs it’s own Drupal stack, which we don’t care about.  In order to connect it to your Git repository, we have to find the path of the acquia-drupal docroot.

On Mac: ~/Sites/acquia-drupal

On PC: //todo: Pc path

Either delete or rename this folder, and then we’ll create a symbolic link from the location Dev Desktop is looking for to the docroot of our git repository.

You’ll also need the path to your Git docroot, which is something like this: /path/to/git_stuff/ucsfp/docroot -- Real world example: ~/git/ucsfp/docroot 

On Mac: ln -s /path/to/git_stuff/ucsfp/docroot ~/Sites/acquia-drupal

On PC: //todo PC Path

Create the symbolic link from where Acquia thinks it's files are to your git docroot.

On Mac: ln -s /path/to/git_stuff/ucsfp/docroot ~/Sites/acquia-drupal

On PC: //todo PC commands

At this point you should be able to run Dev Desktop, and point your browser to http://localhost:8082/, and get a Drupal error.  If you get Acquia happytalk, or nothing at all, something is not quite right.

Setting up Domain Names

The hostfile is a DNS override for your computer.  If you've worked on "dev" or "stage" servers on the acquia environment, you're probably familiar with this.  The hostfile will tell your computer to look for the local version of your site at 127.0.0.1 (localhost).

You'll have to open the hostfile as an administrator, so have your computer password handy!

On Mac: sudo pico /etc/hosts -or- sudo vi /etc/hosts

On Windows: Right-click notepad (or another text editor) and select "Run as Administrator" Then open (File > Open) and navigate to the hosts path (Windows/System32/drivers/etc/hosts

Since Drupal will still match the domain name 1 level up, we'll be adding local. to the beginning of your domain name, to prevent any confusion.  Most of the time this will mean something like local.dev.mysite.ucsf.edu which points to your dev.mysite.ucsf.edu folder.  If for some reason you don't have a dev. folder it will be local.

The format for a hostfile entry is: ip.add.re.ss(tab)full.domain.name

Examples:

127.0.0.1   local.dev.mysite.ucsf.edu

127.0.0.1   local.anothersite.ucsf.edu

Now if you went to local.dev.mysite.ucsf.edu:8082 (note the addition of the port number), you should get a DB error, or install screen, rather than nothingness. If you test this, close the window afterwards.

Local Database Connection 

Copy the code or whole file found in the git repository at ucsfp/docroot/sites/default/default.local.settings.inc and place it in your sites folder and name it local.settings.inc -- this is a special file that Git knows to ignore. (You should be working in your site's folder, likely dev, at this point.) //todo: put this file somewhere more friendly

Open your local.settings.inc, uncomment the "acquia dev desktop" version of the databases array, and change the line that reads:

'database' => 'pharmacy',

To reference a database name for your site, usually the name of your site or something equally concise and descriptive.

'database' => 'mysite',

Also note that this is where you can change the MySQL port number should yours be different.  The username and password supplied there are Dev Desktop standard, and should work fine.

Now open your site's settings.php file at look at the bottom of the file for the Acquia DB include line which looks like: 

if (file_exists('/var/www/site-php')) {

  require('/var/www/site-php/ucsfp/mysite-settings.inc');

}

Immediately after that, follow it with this else if statement:

else if (file_exists(__DIR__ . '/local.settings.inc')) {

  require(__DIR__ . '/local.settings.inc');

}

This little snippet of code basically tells Drupal to look for a local.settings.inc anytime it doesn't find Acquia's database information.

You can do this local.settings.inc procedure, and the database procedures that follow, for any of the sites you are running in the multisite environment.

Database Download

On your dev or production site (more on that later), go to Backup & Migrate (Admin > Configuration > System > Backup & Migrate) to download a current DB.  Make sure the database selected by default appears to match your site, and then download using deafult setting by hitting Backup now. 

NOTE: Make sure that the Compress cached pages found in Performance (Admin > Configuration > Development > Performance) is unchecked, or it will not work on your local system.

Database Creation and Insertion

Open the Acquia Dev Desktop Control Panel and hit Manage my Database.  Near the top of the PhpMyAdmin screen, hit Databases then look for the Create database box and type the name you specified in your local.setings.inc file. 

On the left-hand side list of databases click the name of the database you just created, then at the top click Import.  Under File to Import click Choose File and select the file you just downloaded.  Go to the bottom of the page and hit Go.  This should import your database!

If you need a minor re-import of your database, just follow the procedure starting with Import.

If modules have been changed or updated, sometimes just a re-import is not enough (because of orphaned tables).  It is a good practice anytime modules have changed to go to a SQL input in PhpMyAdmin and drop your entire database (drop database mysite;). After that, just start over with database download and creation.

At this point your site should come up (with a few broken images) at your equivenet to local.dev.mysite.ucsf.edu:8082 -- pat yourself on the back! 

Images and Files

Our environment treats user-uploaded files (including user-uploaded) images as seperate from the database and codebase.  Currently there is no direct support for moving files in this procedure.

Some users will have SSH access that will allow them to grab their files via SCP, SFTP, or RSYNC.  Others may have to request to get a Box or other access to a recent copy of files.

Once obtained, place files in the a files folder inside whichever site folder (usually production) is specified as the Public file system path in File System (Admin > Configuration > Media > File System).  Git will ignore that folder.

Luckly, a most development work can be proceed without the Files, and there is a script in the works which hopefully could make it easier to grab files.