Local Development Guide

Goals

The purpose of this guide is to assist you with creating and installing a new Drupal application on your local machine for the purpose of development. Installing Drupal using the following instructions will give you a starting point for a website that can be deployed to a production environment. The intended audience for this guide is a developer.

Prerequisites

• You should be comfortable using a command-line terminal. See Moving Around the Command Line video tutorial.
• Sufficient system privileges to download and install new software.
• DDEV is a Docker-based tool that provides a preconfigured local development environment for Drupal. Download the Docker community edition for your OS before attempting to install DDEV.

Local development with DDEV

This guide provides instructions for installing Drupal’s system requirements by using a free, cross-platform local development solution, DDEV. Many viable local development environment solutions exist. Note: DDEV requires Docker.

To install DDEV, see DDEV installation documentation.

Configure your local development environment to serve your application

Replace my-site with a machine-friendly (no spaces or special punctuation) name for your new application and run the following command (assumes DDEV):

mkdir my-site
cd my-site
ddev config --project-type drupal10 --create-docroot --docroot web

This will create a new DDEV project configured to host a Drupal application. DDEV will store the generated configuration in a new .ddev subdirectory. Project name will be the same as the parent folder (my-site), define it with --project-name solrcloud.

Next, start the DDEV container

ddev start

You now have a web server and database server configured and running. Configuring DDEV first allows us to run Composer from within DDEV instead of installing it locally.

Create a new Drupal application

Next, use Composer to install Drupal, which enables you to install and update dependencies (modules, themes, profiles, libraries, etc.) also with Composer. It is best practice to ensure that your entire Drupal application is managed with Composer in order to facilitate manageable upgrades.

Now create a new Drupal application with Composer. Note: ddev composer create will unpack and download the files into the current folder, unlike composer create-project which downloads Drupal into a separate folder.

ddev composer create drupal/recommended-project -y

It is possible to install Drupal with Composer without using the DDEV environment, but not recommended, since PHP versions in DDEV and your local environment may differ.

composer create-project drupal/recommended-project

You now have a web server and database server configured and running.

Install Drupal

Next, you must install Drupal using Drush, which populates your Drupal application’s new database.

First, install the latest version of Drush, a command-line utility for Drupal.

ddev composer require drush/drush

Using DDEV and Drush, execute the command below.

ddev drush site:install -y

Drupal is now installed, with an automatically generated password for the user #1 account (Administrator). User name and password for user #1 can be specified with --account-name=myusername --account-pass=my-password.

Log In

Finally, launch your new Drupal site and log in.

ddev launch

You can also generate a one-time login link for the administrator account (user id #1).

ddev drush user:login

If necessary, execute ddev describe to view the URL of your site. Copy and paste that URL into your web browser to visit it.

Next steps

What now?

Learn how you can begin to extend and customize your new Drupal application. Visit the Drupal User Guide and read the following chapters:

• Chapter 4. Basic Site Configuration
• Chapter 5. Basic Page Management
• Chapter 6. Setting Up Content Structure

Appendix

We chose to use DDEV for this local development guide because it met the following criteria:

1. Must be free and open source, without tying users into a proprietary product or service.
2. Must be well maintained, with long term support.
3. Must follow Drupal best practices.
4. Must be compatible with MacOS, Windows, and Linux.

5. Must be as simple as possible

   1. Fewest pre-requisites
   2. Fewest manual steps

To suggest a different local development solution, please create an issue in the Official Docs issue queue.