Launching Drupal site locally with Docker and ddev

After spending waay too much time trying to set up a local nginx web server for an existing Drupal site on Mac, I just had to give up. According to every tutorial on the web it was supposed to be a simple few-step process, however in reality it seemed impossible to configure all the necessary parts to work together.

I'm still not completely sure if the culprit was nginx's r/w/x permissions that I may have not set correctly, or some part of the nginx conf file that I also may have not set up correctly, or, perhaps, Drupal wasn't connecting to the database, or, maybe, it was the php-fpm that was playing a crucial part in the whole setup, but, again, needed to be configured correctly.

The point is, there's too much stuff for a developer to configure. Especially, for a front-end dev such as myself who's used to just typing in a console npm install and npm run start.

Luckily, ddev comes to aid.

Installation

There's a wide variety of tools designed to simplify local development environments for Drupal. In fact, many of them are listed in Drupal docs. In hopes for better performance, I went with ddev because of their support for M1 Macs.

Note: Apple Silicon M1 (ARM64) is supported in v1.17-alpha1+ (edge versions).

To install ddev using Homebrew, use command brew install drud/ddev-edge/ddev or brew install drud/ddev/ddev for a stable version.

Of course, your system also needs Docker to be installed. See ddev docs for docker installation.

Setup

So, let's say you are given a repo that contains a Drupal project along with all the site files. Naturally, the first thing you do is clone the project using git clone https://github.com/example/example-site and cd into it cd example-site.

Next, ddev comes to play. Before you can execute any ddev commands, you need to run ddev config.

Note: All ddev commands need to be launched from the project root folder!

It will walk you through some basic config steps such as project name and project type, but since ddev seems to be pretty good at guessing the appropriate values, I didn't even need to type in anything.

The docs contain quick start guides for all kinds of setups; I was interested in Drupal 9 section and much to my surprise (and relief) there are only two commands to run: ddev composer install and ddev launch.

Note: If you haven't run the mkcert -install command before, now is the time.

If everything runs smoothly, ddev will output a message saying Project can be reached at https://yourprojectname.ddev.site https://127.0.0.1:64124. But before accessing your site, a database needs to be added. In my case, I was provided with a raw SQL dump in a form of a .sql file which I could easily add to the project using ddev import-db --src=/path/to/file/db.sql. Another thing to note - since the project I cloned was previously configured manually, there was a databases configuration left in sites/default/settings.php which needed to be removed since ddev created its own databases config in settings.ddev.php.

And that's it.

It also automatically set up phpmyadmin for us. You can check the port number for it (among other useful stuff) by executing ddev describe command.

To recap

Step 1 - Install Docker

brew install homebrew/cask/docker
// or visit
https://docs.docker.com/docker-for-mac/install/

Step 2 - Install ddev

brew install drud/ddev-edge/ddev
// or
brew install drud/ddev/ddev 

Step 3 - Get your project

git clone https://github.com/example/example-site && cd example-site

Step 4 - Config ddev for your project

ddev config

Step 5 - Install project dependencies

ddev composer install

Step 6 - Import database

ddev import-db --src=/path/to/file/db.sql

ddev launch and done!