Easy Local Drupal Development on OS X

Sometimes getting Drupal to run locally can be a bit of a challenge. You may be working on projects which require a stack that Drupal doesn’t like. Perhaps you’re having a hard time getting your webserver, PHP, and database all talking to each other.

There’s a few tools you can use to make setting up Drupal easier:

You can bug the ops guys, get them to help you set it all up… but you’ll inevitably be back at their desk or bugging them in Slack a week after some random package updates and it all breaks again…
You could download a Vagrant image, work to configure it for your site, make a snapshot… but then have restore back to there when your stack goes awry, or maybe you could use a tool like Puppet or Ansible to re-configure that VM, but if you can pull that off, why aren’t you the office DevOps go-to already?
And then there’s Docker. What a mess! Seemingly random IPs, weird port numbers, hosts file entries, services on different containers, files that disappear when you restart a container. Oy!

How about an option that takes care of all of this pain for you? EnterCachalot. A Docker-compose based local development environment LEMP stack. No knowledge of Docker needed, installable via tools that you probably already have installed, and fast! You can spin up sites in a matter of seconds. It’s what we use here at amazee.io and now we’re sharing it with you.

Running Ubuntu 14.04 LTS, nginx, Varnish 4, PHP-FPM, and MariaDB 10, Cachalot is a package available via Homebrew and only requires you to have a VM provider running locally. We have configurations for PHP 5.6 and 7.0, have Solr available, and fully support sites being built using the most modern methods like Drupal Console and Composer.

So, what’s it actually look like to get this going. First, you’ll need to install a few dependencies and then Cachalot:

brew tap amazeeio/cachalot
brew install docker docker-machine cachalot

Setup the actual VM that runs Cachalot for us:

cachalot create --provider virtualbox

And make sure your shell knows about some Docker environment variables:

eval(cachalot env)

You can also drop that line at the end of your .bash_profile:

echo "eval \$(cachalot env)" >> ~/.bash_profile

Finally, we need to tell Docker what configuration to use, and we need to tell Drupal how to connect to the database.

Letting Docker know what our site wants to run on is simple; we’ve provided a number of example docker-compose.yaml files in a repo on our GitHub.

For this example, let’s just assume we’re working with a basic Drupal 8 site that needs PHP 7.0. Our docker-compose.yml will look like this:

Take note of the hostname: line, this is the only thing which you must edit in the file to have it run.

If your site’s index.php is not located in the root of your repo, add this line (replace web with the correct directory name) immediately below “environment:” This will let nginx know where to find your index.php.

WEBROOT: web

Now, for Drupal to know where to find the database, edit your settings.php file and add this snippet at the very end of the file:

This is just a small part of our provided settings.php files, read more on our documentation about them.

To finish, simply tell docker-compose to start the container:

docker-compose up -d

Docker will now go out and download the relevant images and get them all started.

Be patient, the first download is pretty big, and once you have the image stored locally, starting new sites using it is lightning quick.

After the downloads are done, the container for your site will start, and you’ll see a message, “Creating mylocaldrupal.com.docker.amazee.io.”

You can go ahead and bring the site up in your browser using the hostname entered in docker-compose.yml, just keep in mind you’ll have no database to work with yet.

To get your site’s database in, you can choose from a few familiar methods. The first step to any of these is to connect to the Docker container. From anywhere in the site’s directory structure, you can run the following command and this will deposit you in the webroot of your site.

docker-compose exec --user drupal drupal bash

Now, you can use Drush to import a database from a file in your site’s directory structure, our documentation explains you how to do that.

If the site is hosted on amazee.io you can use the power of Drush aliases and import directly from the dev (or production) environment with one single command. One of the great features of Cachalot is that it will securely bring your SSH keys into the site’s container, so you can use any SSH-based method to bring down databases or files from your existing hosting.

If you run across any problems, amazee.io can help! We’ve got a lot of information in our Docs, and there’s almost always someone online in our public Slack — just join the #docker channel.