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.
Evaluating Drupal? Create a disposable Drupal demo application to evaluate Drupal’s capabilities and codebase.
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. Install Docker 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 drupal --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:
- Must be free and open source, without tying users into a proprietary product or service.
- Must be well maintained, with long term support.
- Must follow Drupal best practices.
- Must be compatible with MacOS, Windows, and Linux.
-
Must be as simple as possible
- Fewest pre-requisites
- Fewest manual steps
To suggest a different local development solution, please create an issue in the Official Docs issue queue.