01/02/2025Creating a Local Drupal Development Environment with DDEV

Setting up a local development environment is a critical step in any Drupal project. It allows you to develop, test, and debug your site without affecting the live environment. In this guide, we’ll walk through the process of creating a local Drupal environment using DDEV, a powerful tool that leverages Docker to simplify local development. For this example, we’ll use develahaye as the project name in commands and URLs.

Why Use DDEV?

DDEV is an open-source tool designed to streamline the creation and management of local development environments for Drupal, WordPress, and other CMS platforms. Here’s why DDEV is a great choice:

• Consistency: DDEV uses Docker to create containerized environments, ensuring consistency across different operating systems.
• Ease of Use: DDEV abstracts away much of the complexity of Docker, making it accessible even for developers who aren’t familiar with containerization.
• Integration: DDEV integrates seamlessly with tools like Drush, Composer, and Xdebug, making it a robust solution for Drupal development.

Prerequisites

Before we begin, ensure you have the following installed on your machine:

1. Docker: DDEV relies on Docker to create containerized environments. Download and install Docker from docker.com.
2. DDEV: Install DDEV by following the official installation guide at ddev.com.
3. Terminal Access: Familiarity with using the command line is essential for working with DDEV.

Step 1: Set Up a New DDEV Project

1. Create a Project Directory:
   Open your terminal and create a new directory for your project. For this example, we’ll use develahaye as the directory name. Navigate into the directory:

   mkdir develahaye
   cd develahaye

2. Initialize DDEV:
   Run the following command to initialize a new DDEV project:

   ddev config

   DDEV will prompt you for some basic information:

   • Project name: Enter develahaye. This will be used to generate the local URL (e.g., develahaye.ddev.site).
   • Docroot: For Drupal, this is typically web.
   • Project type: Choose drupal9 or drupal10 depending on your version.

   Once configured, DDEV will generate a .ddev directory with configuration files.

3. Start the DDEV Environment:
   Start the local environment by running:

   ddev start

   This command will spin up the necessary Docker containers for your project. Once the environment is running, DDEV will provide you with URLs to access your site locally (e.g., https://develahaye.ddev.site).

Step 2: Install Drupal

With your local environment running, the next step is to install Drupal. Instead of using the browser-based installer, we’ll use Drush, a command-line tool for Drupal that simplifies many tasks, including site installation.

1. Download Drupal:
   Use Composer to download Drupal into your project directory. Run the following command:

   ddev composer create drupal/recommended-project

   This will download the latest version of Drupal and its dependencies into your project.

2. Set Up the Database:
   DDEV automatically creates a MySQL database for your project. You can find the database credentials in the .ddev/config.yaml file or by running:

   ddev describe

   The database credentials will include:

   • Database name: db
   • Username: db
   • Password: db
3. Ensure valid php/mariadb Compatibility: At this point you may come across errors stating that your version of php or mariadb is incompatibile with drupal, if this is the case then change the php version in .ddev/config.yaml or run ddev debug migrate-database mariadb:VERSION and restart ddev with ddev restart
4. Install Drush:
   Drush makes it easy to install Drupal from the command line, this can be required with composer with the following command:

5. Install Drupal Using Drush:
    

   Then run the following command to start the installation:

   ddev drush site:install --site-name="develahaye" --account-name=admin --account-pass=admin

   Here’s what each option does:

   • --site-name="develahaye": Sets the name of your site.
   • --account-name=admin: Creates an admin user with the username admin.
   • --account-pass=admin: Sets the admin user’s password to admin (change this to something more secure in a real project).

   Drush will automatically use the database credentials from your DDEV configuration, so you don’t need to enter them manually.

6. Generate a One-Time Login Link:
   After the installation is complete, generate a one-time login link for the admin user using the following command:

   ddev drush uli

   This will output a URL that looks something like this:

   http://develahaye.ddev.site/user/reset/1/1698765432/abc123def456/login

   Copy and paste this URL into your browser to log in as the admin user without needing to enter a password.

7. Verify the Installation:
   Once you’ve logged in, you’ll be redirected to the Drupal admin dashboard. This confirms that the installation was successful and that your site is fully functional.

Step 3: Develop and Test Locally

With Drupal installed, you’re ready to start developing. Here are some key tasks and tips:

1. Run Drush Commands:
   DDEV makes it easy to run Drush commands. For example, to clear the cache, run:

   ddev drush cr

2. Manage Dependencies with Composer:
   Use Composer to install and update Drupal modules and themes. For example, to install the Pathauto module, run:

   ddev composer require drupal/pathauto

3. Enable Xdebug for Debugging:
   DDEV comes with Xdebug preconfigured. Enable it by running:

   ddev xdebug on

   Then, configure your IDE to listen for Xdebug connections. This allows you to step through your code and debug issues effectively.

4. Sync Files and Database:
   If you need to sync your local environment with a remote site, you can use DDEV’s import/export commands. For example, to import a database dump:

   ddev import-db --file=path/to/dump.sql.gz

Step 4: Stop and Clean Up

When you’re done working, you can stop your local environment by running:

ddev stop

If you need to remove the environment entirely, use:

ddev delete

Final Thoughts

Setting up a local Drupal development environment with DDEV is a straightforward process that can significantly improve your workflow. By leveraging DDEV’s powerful features, you can ensure consistency across environments, streamline development, and focus on building great Drupal sites.

For more advanced configurations and tips, refer to the official DDEV documentation. Happy coding!