How I learned to stop worrying and love local Drupal development

The author’s cat and mouse.

Part 2 - Kicking down doors: My Drupal journey from site builder to developer

The Drupal community needs more people to try Drupal, but there is a giant hurdle at the beginning of the relationship that sends many would-be ambitious site builders running: setting up a local development environment.

Sure, there are Web hosts that offer single click installs, great for trying out Drupal, but we need to get our hands dirty in the code, so that won’t help us.

The official Drupal documentation is informative, but loaded with jargon which may block the uninitiated. The truth is, there have been giant leaps made in how we can set up development environments in recent years, so it should be easy once we choose a path.

Let’s back it up about 10,000 feet

I want to make sure we are on the same page here with what we are trying to accomplish. We want to create and edit custom code added to an instance of Drupal core and see the results in a browser. Simple, right?

Browsers operate in the same way that they have since the beginning of time: they create a document object model (DOM) from HTML, style it visually with CSS, and run client-side JavaScript to manipulate the DOM and the CSS. Go ahead and try it! Drag an HTML file to your browser and BOOM, there it is.

Great. So why don’t we just do that with our Drupal files? Because Drupal is not a collection of HTML files, it is a collection of PHP and Twig templates connected to a database. They need to be preprocessed by a Web server and turned into HTML. Great. How do we get a Web server with PHP and a database? Simple. Containers.

Try to contain your excitement

I will refrain from the “Back in my day…” story about the crazy things we used to have to do to set this up. Today we have Docker containers where any number of servers and configurations can be run on your desktop or in the cloud. Someday it will be even easier and you can tell stories of how you had to deal with this, but right now, this is pretty cool.

Docker containers are infinitely versatile, and equally complicated to set up. I guess we could look up Drupal’s requirements and find Docker images for each of the pieces we need and — wait, where are you going? Come back! We don’t have to do any of that. DDEV has does it all for us!

Check out this message currently pinned to the top of the Local Development page on Drupal.org:

The recommended Drupal local development environment for macOS, Linux, and Windows is a Docker-based solution such as DDEV or Lando instead of setting up a local server manually.

Now we have the clue we have been looking for: DDEV or Lando. If you haven’t heard of either before, they are both tools for creating local Docker-based PHP development environments. Well, that checks all the boxes. So which one? They each have their fans. I have had good experiences with DDEV, so let’s choose that one.

[Why don’t they just pick one and build it right into Drupal? Remember in the introduction to this series when I told you how I don’t like boxes? Well the Drupal community doesn’t either. Drupal must be able to exist in whatever development workflows that exist now and in the future. They may recommend one over another, but don’t expect one method to become the default. That might close the door on some other method, and we dislike doors even more than boxes!]

Are you ready to get started? Take a deep breath. Our journey is going to being with the command line.

Wait! Don’t run.

I know you are either thinking, “I am very comfortable with the command line and don’t need your hand holding,” or “Please, I need some hand holding!” Either way, no hand holding from me. There are better resources for that (I will share one below). I just want to point out a couple of things.

I already told you that I don’t like boxes, and the command line was one box that made my blood run cold. Some people are drawn to it like their first language, while others can live happy productive lives never once interacting with the command line. Trying to use it for the first time is intimidating. It should be. It’s very powerful and usually not clear how to undo whatever you just did.

So for some of you, this is a major door to kick down. If you need some encouragement, here is a guide from Drupalize.me to help you do that: Command Line Basics. But don’t take too long! You don’t need to be an expert, just overcome your fear. The rest of us will meet you in the next chapter when you are ready.

Installing DDEV

You are just two commands away from creating your first DDEV project. The DDEV “Get Started” guide will walk you through it. Simple, right?

But where is Drupal? DDEV has us covered once again with a list of “CMS Quickstarts” including how to get a fresh install of specific Drupal versions or how to clone an existing project.

You can simply copy and paste the list of commands into your command line, but let’s break it down and see what is going on. Here are the step for a fresh Drupal 10 install.

mkdir my-drupal-site && cd my-drupal-site

Create a directory called “my-drupal-site,” or whatever you want your project to be named, then change directories to this new project directory.

ddev config — project-type=drupal — php-version=8.3 — docroot=web

This is the DDEV configuration command. We tell DDEV to make this a Drupal project so it will include some specific Drupal commands. We tell it to use PHP version 8.3 which is the version currently required by the latest Drupal release. And we tell it that the docroot, where we want to serve our web pages from is the directory named “web.” If you clone a project or install a custom distribution of Drupal, your docroot may be something different and you can set that here.

ddev start 

Let’s fire up DDEV. You can watch the command line as DDEV pulls Docker Images and creates our servers. When they are ready it will list the URLs we can use to see our project in the browser, but don’t bother yet, we still have to install Drupal.

ddev composer create drupal/recommended-project:^10

Here is the standard Composer command to install a fresh Drupal 10 project. Not familiar with Composer? It’s a PHP package manager and keeps track of all of our Drupal dependencies. DDEV installs it when you create a Drupal project. Notice when we run a composer command, we must put “ddev” in front so it will run it from our new container and look for it on our local machine.

We can watch the command line as Composer downloads and installs the dependencies, hopefully ending with a nice confirmation message.

ddev config — update

Now, with Drupal installed, we can update the DDEV configuration so it can fill in more specifics.

ddev composer require drush/drush

Drush is a Drupal command line tool that will help us with many tasks moving forward. There are times when specific version of Drush is needed for specific projects, so DDEV leaves this to us to add to our project if desired. It is. So we do.

ddev drush site:install — account-name=admin — account-pass=admin -y

Next, we use Drush to finish up our Drupal installation. If you had visited the project URL before this step you would have seen Drupal’s interface for manually entering this data. You can do it there if you like, but this is a quick one-line command to get it done fast! As you can see it includes the creation of a username and password for our administrator user. You can make these whatever you like.

ddev drush uli

This is one of the handiest Drush commands. It provides you with a one-time login link, so even if you forget the credentials you set in the previous step, you have a backdoor to your site.

ddev launch

And finally, DDEV will open your browser with your newly created local Drupal development site.

Consider this door kicked down! Now we can get to the fun stuff. Join me next time as we kick down the door of creating a custom theme.