Launching Drupal site locally with Docker and ddev
Tags: drupal, docker, ddev, nginx
Published: 2021-06-29 15:13:39

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](https://www.drupal.org/docs/develop/local-server-setup/docker-development-environments/docker-solutions-overview). In hopes for better performance, I went with **[ddev](https://ddev.readthedocs.io/en/stable/)** 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](https://ddev.readthedocs.io/en/stable/users/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](https://ddev.readthedocs.io/en/stable/users/cli-usage/) 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!