Drupal 10 on Windows with Docker and DDEV for Multi-Tenant Subdomains

If you are still running Drupal locally with XAMPP on Windows, you have probably already run into the usual problems: slow file syncing, configuration drift, hardcoded database settings, and trouble when you need more than one local environment. Those issues become even more visible when the project uses tenant-based subdomains.

This setup replaces that older workflow with Docker and DDEV. The result is a cleaner local environment for Drupal 10, easier database handling, and support for subdomains that fit a multi-tenant SaaS structure.

What You Need Before You Start

Windows 10 version 2004 or later, or Windows 11
Virtualization enabled in BIOS
WSL2 installed
Docker Desktop
DDEV
A Drupal 10 codebase

Install WSL2

Open PowerShell as Administrator and run:

wsl --install

Restart your system after the installation. Then verify the status:

wsl --status

The default version should be set to version 2.

Install Docker Desktop

Download Docker Desktop and install it using the WSL2 backend. During setup, keep Linux containers (Use WSL2 instead of Hyper-V)enabled and do not switch to Windows containers.

After installation, make sure Docker starts correctly, then verify it from PowerShell:

docker --version docker run hello-world

If the second command returns the standard hello-world message, Docker is ready.

Install DDEV

If Chocolatey is not installed yet, install it first from an elevated PowerShell window:

Set-ExecutionPolicy Bypass -Scope Process -Force; ` [System.Net.ServicePointManager]::SecurityProtocol = ` [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; ` iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

Then install DDEV:

choco install ddev -y

Check the installation:

ddev version

Move the Project Out of XAMPP

If your Drupal project is still inside a XAMPP directory, move it to a normal working folder such as:

C:\Users\Admin\projects\sample_site

This avoids common file system and performance issues on Windows.

Configure the Drupal Project with DDEV

Go to the project folder and run:

cd C:\Users\Admin\projects\sample_site ddev config

Use these values when prompted:

Project name: sample-site
Docroot: web
Project type: drupal10

Then start the project:

ddev start

Once it starts successfully, the site should be available at:

http://sample-site.ddev.site

Import the Existing Database

Export your current database from phpMyAdmin or your existing local setup as an SQL file. Then import it into DDEV:

ddev import-db --src=C:\path\to\sample.sql

This gives you the same content and structure inside the new environment without manually rebuilding the database.

Update settings.php

Open web/sites/default/settings.php and remove any old XAMPP-specific database settings. Make sure the DDEV settings file is included:

if (file_exists(__DIR__ . '/settings.ddev.php')) { include __DIR__ . '/settings.ddev.php'; }

That keeps your local database configuration aligned with DDEV instead of hardcoded credentials.

Set Trusted Host Patterns

When you are using subdomains locally, trusted host configuration matters. Add this to settings.php:

$settings['trusted_host_patterns'] = [ '^sample-site\.ddev\.site$', '^.+\.sample-site\.ddev\.site$', ];

Then rebuild the Drupal cache:

ddev drush cr

Share Sessions Across Subdomains

In a multi-tenant local setup, you may want users to stay logged in across tenant subdomains. For that, set the cookie domain in services.yml:

parameters: session.storage.options: cookie_domain: '.sample-site.ddev.site'

That allows the session cookie to be shared across the parent domain and its subdomains.

This is useful when testing flows such as switching between a main tenant, an admin area, or multiple client subdomains without repeated logins.

Configure Wildcard Subdomains in DDEV

For multi-tenant routing, update .ddev/config.yaml and add an additional hostname entry:

name: sample-site type: drupal10 docroot: web additional_hostnames: - "*.sample-site"

Restart DDEV after the change:

ddev restart

You should then be able to reach routes such as:

sample-site.ddev.site hq.sample-site.ddev.site client-abc.sample-site.ddev.site client-xyz.sample-site.ddev.site

Optional: Add phpMyAdmin

If you still want a browser-based database tool, use the DDEV add-on rather than mixing XAMPP services into the project:

ddev add-on get ddev/ddev-phpmyadmin ddev restart ddev launch -p /phpmyadmin

To check the current service URLs and project details, run:

ddev describe

Useful DDEV Commands

ddev start ddev stop ddev restart ddev drush cr ddev import-db --src=file.sql ddev logs ddev launch

Why This Setup Works Better

This approach keeps the local environment closer to a container-based deployment model. It also makes it easier to work on more than one project, keep configuration predictable, and test subdomain-based tenant routing without manual host file edits.

For Drupal teams building SaaS-style platforms, that makes a real difference. You spend less time fixing local environment issues and more time working on the application itself.

Final Thoughts

Moving from XAMPP to Docker and DDEV on Windows is not just a tooling change. It gives you a more reliable local stack for Drupal 10 and makes multi-tenant development much easier to manage.

If your project uses subdomains per client or tenant, this setup is a practical starting point that is easier to maintain and closer to how modern environments are expected to behave.

Drupal