The Simplest Path to a Drupal Local Environment

by Andrew Berry

After my article about Drupal Development Environments, we had some discussions about the differences junior developers see when using Drupal and PHP applications locally, compared to React and other front-end tools. Someone mentioned how easy it was for them to get started by running yarn serve in a React project, and I was curious how close to that we could get for Drupal.

To make this a fair comparison, I’m not including managing MySQL databases and the like. Most React apps don’t use a database directly, and if you do need to run backend services locally, the complexity goes way up. In between writing and publishing this article, Stranger in a familiar land: Comparing the novice's first impression of Drupal to other PHP frameworks was published, which constrained itself to using the Drupal GUI installer. I think this guide shows that we can run Drupal locally in very few steps as long as we don't force ourselves to use a GUI.

I also wanted to see what the “new laptop” experience was like. I’ve been migrating my macOS setup between computers for nearly 15 years (if only Windows worked as well!), and it’s easy to forget what exactly is built in and what I’ve added over time. So, I installed a fresh copy of High Sierra in VirtualBox to ensure none of my terminal or Homebrew customizations were giving me a leg up.

Installing Composer

We need Composer to install Drush. Change to the drupal directory in the terminal (cd drupal), and run the Composer installation instructions to download composer.

When composer is done, you will have a composer.phar file in your Drupal directory.

Installing composer

Installing Drush and Drupal

Drush is what will let us easily run Drupal using the built-in PHP webserver. It’s also required to do the initial site installation. Pull Drush into your Drupal site by running:

$ composer require drush/drush

This will not only pull in Drush, but it will also install all of the other libraries Drush needs at the same time.

Once Drush is installed, we have to use it to install Drupal. Drupal does have a graphical installer, but Drush won’t run the PHP webserver unless Drupal is already installed. The most important parameter is the database URL, which tells Drupal what database server to use and how to connect to it. We’re going to use SQLite, which is a simple single-file database. We don’t want the database file itself to be accessible from the web server (in case it’s ever exposed to respond to external requests), so we tell Drupal to put the database in a directory above our Drupal document root.

$ vendor/bin/drush site-install --db-url=sqlite://../drupal.sqlite

Installing Drush

When the installation is done, Drush will tell you the administrator password. If you ever forget it, you can reset it by generating a login link with drush user-login.

Running the Drupal Web Server

To start the web server, use the runserver command:

$ vendor/bin/drush runserver

By default, the server will listen on Run vendor/bin/drush help runserver to see how to change these and other defaults.

Finally, open that URL in a browser. You should see the Drupal 8 home page and be able to log in with the administrator account shown earlier. Press CTRL-C in the terminal to shut down the web server.

Running the PHP webserver

The default macOS PHP configuration is pretty good, though it sets a very low limit of 2MB for uploaded files. If you need to raise it, copy /etc/php.ini.default to /etc/php.ini with:

sudo cp /etc/php.ini.default /etc/php.ini

Then, edit it with sudo nano /etc/php.ini to change settings as you see fit. You will need to restart the Drush web server after changing this file.

Bonus: Installing Git and Cloning Drupal

I like to use git even for basic testing because I can run git status at any time to see what files I’ve changed or added. I opened the Terminal and ran the git clone command copied from the Drupal project page.

$ git clone --branch 8.5.x

The first run of this command prompts to install the developer tools:

Installing git

After they install, you need to rerun the git command again (which is accessible by pressing the up arrow on your keyboard).

When this initial clone is done, you will have a Drupal 8.5.x checkout in a folder called “drupal,” and you can go back to the earlier steps to install and run Drupal.

Next Steps

Now that you have a running Drupal 8 site, it’s easy to try out contributed modules or new experimental modules without worrying about breaking a real site. It’s easy to run a “clean” instance of Drupal 8 later, by reinstalling the current site with drush site-install, or by creating a new Drupal git clone separate from the first one. And, if you are evaluating Drupal and decide to use it for a real website, you can set up a better development environment without having to learn Composer and Drush at the same time.