Installing Docker, DDEV & Drupal in WSL2

This page explains how to install DDEV & Drupal in the Windows Subsystem for Linux (WSL2). It also offers some basic guidance on using and extending DDEV for Drupal projects.

This is part of a tutorial for setting up Drupal with DDEV in the Windows Subsystem for Linux (WSL2). Experienced users may prefer to follow the instructions to install Drupal using DDEV.

Refer to these resources for help with DDEV:

• DDEV - Get Started
• DDEV Docs - DDEV Installation - Windows
• DDEV Discord Server. Invitation here
• # ddev channel on the Drupal Slack

Having installed WSL2 and Ubuntu, you are now ready to install DDEV. There is no need to manually install Docker Engine before installing DDEV; the DDEV installer will do that for us.

Download the DDEV Windows Installer for your architecture (usually amd64) from DDEV releases. This will be something like ddev_windows_amd64_installer.v1.24.7.exe. 

Run the installer. Select the first option, "Docker CE". Then choose the distro where you want to install DDEV.

When finished, in an Ubuntu terminal app (or Ubuntu within your Windows Terminal), confirm that DDEV is installed by entering ddev version.

Now you can use the Ubuntu terminal to access your Ubuntu distribution, which has DDEV and Docker working inside it.

For comprehensive guidance on using DDEV, consult the DDEV Docs.

Keep DDEV up to date

Upgrade DDEV when required, along with other Debian packages, by running:

sudo apt update && sudo apt upgrade -y

Install a Drupal project

Guide: DDEV - Drupal CMS Quickstart (Very brief. More detail is given below)

At your Ubuntu prompt, be sure you are in your home directory by checking the information at your prompt and entering ~ if necessary.

There are multiple files and folders in your home directory and there will be more as you develop, many of them hidden (with a . in front of them). If you plan to develop multiple projects, it's a good idea to have a parent folder for them within your home directory. Use a concise name such as sites, projects or proj. Make the directory and change into it:

mkdir sites
cd sites

Now make a folder for your Drupal project, in this case Drupal 11, and change into it:

mkdir my-drupal11-site
cd my-drupal11-site

Now set up a DDEV project with the requirements for Drupal, including appropriate versions of PHP, MariaDB and Composer. This will create a .ddev folder within your project folder, and within it will be a config.yml file listing the various settings of your project. For Drupal 11:

ddev config --project-type=drupal11 --docroot=web

Now start this DDEV project and let it build a Docker container. On the first run this will take time and you will have a choice whether to send anonymous usage statistics and errors to DDEV:

ddev start

Next, use the local Composer in our DDEV project to create a Drupal project (within our DDEV project) using the Drupal recommended project structure.

If you are in the habit of issuing composer... commands, be very careful not omit the ddev prefix, because a global version of Composer may be used, with undesired results.

To install the current, official release of Drupal, run:

ddev composer create-project drupal/recommended-project

Alternately, you can install a specific version of Drupal by adding its number after a colon. The choices are listed on Packagist. Note that the major version should match the DDEV project type you set above.

ddev composer create drupal/recommended-project:9.5.11

ddev composer create drupal/recommended-project:10.2.x-dev

Install Drush, a command line shell and Unix scripting interface for Drupal:

ddev composer require drush/drush

Use Drush to install the site and set up the admin (user #1) account with name admin and password admin. Again, this will take time:

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

Display a one-time login link in your terminal:

ddev drush uli
# Or ddev launch $(ddev drush uli)

Now CTRL + click the link shown in your terminal. Your new Drupal site should open in your default browser at a page where you can set a new admin password. If you receive a warning about a potential security risk, or that your connection is not private, accept the risk and continue.

Launching your site

To launch your site on further occasions, enter ddev launch at your Ubuntu prompt. If your DDEV project is not started, DDEV will start it for you before opening the site.

Default browser

ddev launch uses the Windows explorer.exe to launch the Windows-side default browser.

DDEV commands

Here are a few common DDEV commands for Drupal developers. Most of them apply to the project whose folder you are within when you run them.

• ddev - List out DDEV commands.
• ddev help command-name - Display help about a specific command.
• ddev list - List projects and their status.
• ddev start - Start a project. Note that many other DDEV commands will automatically start the project before they run.
• ddev launch - Launch the project in a browser.
• ddev stop - Stop the project.
• ddev restart - Restart the project.
• ddev poweroff - Stop all projects.
• ddev composer ... - Run a Composer command.
• ddev drush ... - Run a Drush command.
• ddev git ... - Run a Git command.

For more commands, see the DDEV docs - Commands.

Extending DDEV

It is recommended to read through the extensive guidance on extending and customizing DDEV in the DDEV Docs. Both official and contrib DDEV add-ons can be found in the The DDEV Add-on Registry, including some Drupal-specific add-ons.

DDEV Drupal Contrib

The DDEV Drupal Contrib add-on offers DDEV integration for developing Drupal contrib projects. Install and set it up like this:

ddev add-on get ddev/ddev-drupal-contrib
ddev restart
ddev poser
ddev symlink-project

The add-on's README explains what the above commands do, and list a number of commands that you then have available for testing your code and validating it against coding standards.

BrowserSync

One additional service you may wish to install, especially for working on Drupal themes, is BrowserSync, which allows you to view changes you make to files as you save them, without reloading your browser. Install and enable it like this:

ddev add-on get ddev/ddev-browsersync
ddev restart
ddev browsersync

Add :3000 to the domain in your browser address bar to see the automatically-updating version. e.g. https://my-d11-site.ddev.site:3000 or https://my-d11-site.ddev.site:3000/some-page.php.

Database management

You can always issue SQL queries on your Drupal project's database by typing ddev mysql to enter a MySQL/MariaDB client in your terminal (CTRL + C to exit), without installing any additional services.

However, if you ever need a GUI to inspect the Drupal database for debugging etc., you have a few choices:

• Adminer - Lightweight GUI interface in your browser. Install: ddev add-on get ddev/ddev-adminer && ddev restart. Run: ddev adminer.
• phpMyAdmin - Browser GUI. Lets you edit cells directly. Install: ddev add-on get ddev/ddev-phpmyadmin && ddev restart. Run: ddev phpmyadmin.
• Standalone Apps - If you want to use a standalone GUI app such as MySQL Workbench or DBeaver, you'll probably want to set a static port so it can remember your connection details including password. Add, for example, host_db_port: "59002" to your project's .ddev/config.yaml file. Then run ddev restart, then ddev describe and look for the Host port in the db section. e.g. 127.0.0.1:59001. You can then use these details to configure your connection in the app. By default, the username is db and the schema (database name) is db (or root and root).
• IDE - In VS Code you can use Weijan Chen's MySQL extension (3 connections for free), or Oracle's own MySQL Shell for VS Code extension (still in preview status). PhpStorm has its own Data editor and viewer.

Further guidance: DDEV Docs - Database GUIs.

Next steps

With WSL2, Docker, DDEV and Drupal installed, you are now ready to integrate Visual Studio Code with this environment, should you wish.