How to Use DDEV to Quickly Spin Up Craft CMS and Other Popular Platforms

DDEV changes that completely. This Docker-based tool gives you consistent, reproducible development environments for Craft CMS, WordPress, Drupal, and dozens of other platforms. In this guide, you'll learn exactly how to set up DDEV, spin up a new Craft CMS 5 project in minutes, and configure it for your specific needs.

Prerequisites

Before getting started, you'll need three things installed on your machine:

1. Docker Desktop - The foundation that DDEV runs on

• Download from docker.com/products/docker-desktop/
• Make sure it's running before proceeding

2. DDEV itself - The tool we'll be using

• Installation varies by operating system
• Full guide at ddev.readthedocs.io/en/stable/#installation

3. Composer - For managing PHP dependencies

• Required for installing Craft CMS and its plugins
• Get it from getcomposer.org

Once you have these installed, verify everything is working by running:

docker version
ddev version
composer --version

If all three commands return version information, you're ready to go.

Step-by-Step: Setting Up Craft CMS 5 with DDEV

Let's walk through creating a brand new Craft CMS 5 project. These same principles apply to other platforms, which we'll cover later.

Step 1: Create Your Project Directory

Start by creating a new directory for your project and navigating into it:

mkdir my-craft-site
cd my-craft-site

Step 2: Configure DDEV for Craft CMS

Now tell DDEV what kind of project this is:

ddev config --project-type=craftcms --docroot=web --create-docroot

This command does three important things:

• Sets the project type to craftcms, which tells DDEV to use Craft-specific settings
• Defines web as your public directory (Craft's default)
• Creates the web directory if it doesn't already exist

Step 3: Start the DDEV Environment

ddev start

This pulls the necessary Docker containers and starts them. You'll see output showing the database being created and services starting up. The first time you run this, it might take a few minutes as Docker downloads the required images.

Step 4: Install Craft CMS

With DDEV running, install Craft CMS using Composer:

ddev composer create -y "craftcms/craft"

This downloads Craft CMS 5 and all its dependencies. The -y flag automatically answers "yes" to Composer's prompts about removing existing files.

Step 5: Complete the Setup Wizard

After Composer finishes, Craft's setup wizard will start automatically in your terminal. You'll be prompted to:

• Set your admin username and password
• Configure your site name and URL
• Choose your preferred language

DDEV has already configured your database connection, so you don't need to worry about those details.

Step 6: Access Your New Site

Your site is now ready! Access it at:

https://my-craft-site.ddev.site

Or simply run:

ddev launch

This opens your default browser to the correct URL.

Setting Up Other Popular Platforms

The process for other CMSs follows the same pattern. Here are quick setups for the most common platforms:

WordPress

mkdir my-wordpress && cd my-wordpress
ddev config --project-type=wordpress --docroot=public --create-docroot
ddev start
ddev composer create "johnpbloch/wordpress" .
ddev launch

WordPress uses public as its document root by convention when installed via Composer.

Drupal 11

mkdir my-drupal && cd my-drupal
ddev config --project-type=drupal11 --docroot=web --create-docroot
ddev start
ddev composer create "drupal/recommended-project:^11" .
ddev launch

Drupal 11 requires PHP 8.2 or higher, which DDEV handles automatically when you specify the drupal11 project type.

Laravel

mkdir my-laravel-app && cd my-laravel-app
ddev config --project-type=laravel --docroot=public --create-docroot
ddev start
ddev composer create "laravel/laravel:^12" .
ddev launch

Laravel's artisan commands work perfectly within DDEV using ddev exec.

Code Examples and Configuration

Understanding DDEV's configuration helps you customize environments for your specific needs. Let's look at the key configuration file and some practical examples.

The Main Configuration File

After running ddev config, you'll find a .ddev/config.yaml file in your project. Here's what a typical Craft CMS configuration looks like:

name: my-craft-site
type: craftcms
docroot: web
php_version: "8.2"
router_http_port: "80"
router_https_port: "443"
xdebug_enabled: false
additional_hostnames: []
additional_fqdns: []
database:
  type: mariadb
  version: "10.6"

You can modify this file to change PHP versions, add custom hostnames, or adjust database settings.

Adding Vite for Asset Building

Many Craft CMS projects use Vite for handling JavaScript and CSS. Here's how to configure DDEV to run Vite automatically:

# Add to .ddev/config.yaml
nodejs_version: '20'
web_extra_exposed_ports:
  - name: vite
    container_port: 3000
    http_port: 3000
    https_port: 3001
web_extra_daemons:
  - name: 'vite'
    command: 'npm install && npm run dev'
    directory: /var/www/html

This configuration:

• Installs Node.js 20 in your container
• Exposes Vite's development server ports
• Automatically runs npm install and starts the dev server

Custom PHP Settings

Need to adjust PHP memory limits or execution time? Create .ddev/php/custom.ini:

memory_limit = 512M
max_execution_time = 120
upload_max_filesize = 100M
post_max_size = 100M

DDEV automatically applies these settings when you restart.

Database Imports and Exports

Working with existing projects often means importing databases. DDEV makes this straightforward:

# Import a database
ddev import-db --file=backup.sql.gz

# Export current database
ddev export-db --file=backup.sql.gz

# Access database directly
ddev mysql

The import command handles various formats including .sql, .sql.gz, and .zip files.

Common Mistakes to Avoid

We've found that developers new to DDEV often run into the same issues. Here's how to avoid them:

1. Forgetting to Start Docker Desktop

DDEV requires Docker to be running. If you get errors about Docker not being available, check that Docker Desktop is running in your system tray or menu bar.

2. Port Conflicts

If another service is using ports 80 or 443, DDEV won't start. You have two options:

Stop the conflicting service:

# On macOS, stop Apache
sudo apachectl stop

# On Windows, stop IIS
iisreset /stop

Or change DDEV's ports in .ddev/config.yaml:

router_http_port: "8080"
router_https_port: "8443"

3. Wrong Database Credentials in .env

DDEV automatically creates database credentials. Always use these values in your .env file:

DB_SERVER=db
DB_PORT=3306
DB_DATABASE=db
DB_USER=db
DB_PASSWORD=db

Run ddev describe to see all connection details.

4. Not Committing .ddev Configuration

Your .ddev directory should be in version control. This ensures everyone on your team uses identical environments. Add this to your .gitignore:

.ddev/db_snapshots
.ddev/import-db

But commit everything else in .ddev/.

5. Running Commands Outside DDEV

Always run Composer, npm, and artisan commands inside DDEV:

# Wrong
composer require craftcms/commerce

# Right
ddev composer require craftcms/commerce

This ensures you're using the correct PHP version and have access to all dependencies.

Testing and Verification Steps

After setting up your project, verify everything is working correctly:

1. Check Service Status

ddev describe

This shows all running services, URLs, and database credentials. All services should show as "running."

2. Test Database Connection

ddev mysql -e "SHOW TABLES;"

This lists all database tables. For a new Craft installation, you should see tables like craft_elements, craft_users, etc.

3. Verify PHP Version

ddev exec php -v

Ensure you're running the expected PHP version for your project.

4. Test Mail Functionality

DDEV includes Mailhog for catching emails:

https://my-craft-site.ddev.site:8025

Send a test email from your application and verify it appears in Mailhog.

5. Check Site Access

Try accessing your site via:

• The HTTPS URL: https://my-craft-site.ddev.site
• The HTTP URL: http://my-craft-site.ddev.site
• The direct port if customized: http://localhost:8080

All should work, with HTTPS being the default.

6. Validate Composer Dependencies

ddev composer validate
ddev composer check-platform-reqs

These commands ensure your composer.json is valid and all platform requirements are met.

Advanced Configuration Tips

Once you're comfortable with basic DDEV usage, these advanced techniques can improve your workflow:

Using DDEV Hooks

Automate repetitive tasks with hooks in .ddev/config.yaml:

hooks:
  post-start:
    - exec: composer install
    - exec: php craft migrate/all
    - exec: php craft project-config/apply

These commands run automatically after ddev start.

Adding Redis for Caching

Install the Redis add-on:

ddev get ddev/ddev-redis

Then configure Craft to use it in config/app.php:

'components' => [
    'redis' => [
        'class' => yii\redis\Connection::class,
        'hostname' => 'redis',
        'port' => 6379,
        'database' => 0,
    ],
],

Setting Up Multiple Sites

Run multiple projects simultaneously by ensuring unique names:

# Project 1
ddev config --project-name=client-site

# Project 2  
ddev config --project-name=internal-tool

Each gets its own URL and database.

Sharing Your Local Site

Need to show a client your work in progress? Use ngrok:

ddev share

This creates a public URL that tunnels to your local site. Perfect for quick demos or webhook testing.

Working with Existing Projects

Teams we work with report that migrating existing projects to DDEV is often easier than expected. Here's a typical migration workflow:

1. Clone Your Repository

git clone https://github.com/your-org/your-project.git
cd your-project

2. Configure DDEV

If the project already has .ddev/config.yaml, just run:

ddev start

Otherwise, configure it:

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

3. Install Dependencies

ddev composer install
ddev npm install  # if you have frontend build tools

4. Import the Database

Get a database dump from your staging or production environment:

ddev import-db --file=production-backup.sql.gz

5. Update Environment Variables

Copy .env.example to .env and update with DDEV's database credentials:

cp .env.example .env
# Edit .env with DDEV's credentials

6. Apply Project Config

For Craft CMS projects:

ddev exec php craft project-config/apply

7. Build Frontend Assets

If your project uses build tools:

ddev npm run build
# or
ddev npm run dev  # for development mode

Your existing project should now be running locally with DDEV.

Performance Considerations

DDEV performs well out of the box, but you can make it even faster:

Use Mutagen for File Sync (macOS)

On macOS, enable Mutagen for better file system performance:

ddev config --performance-mode=mutagen
ddev start

This dramatically speeds up operations on projects with many files.

Allocate Sufficient Docker Resources

In Docker Desktop settings, allocate at least:

• 4GB RAM (8GB preferred)
• 4 CPUs
• 60GB disk space

Disable Unused Services

If you don't need certain services, disable them:

# .ddev/config.yaml
omit_containers: ["ddev-ssh-agent"]

Use Production-like Settings

Match your production environment's PHP version and database type:

php_version: "8.2"
database:
  type: mysql
  version: "8.0"

This helps catch compatibility issues early.

Troubleshooting Guide

When things go wrong, here's how to fix common issues:

DDEV Won't Start

1. Check Docker is running
2. Look for port conflicts: ddev logs
3. Try a full reset: ddev poweroff && ddev start

Slow Performance

1. Enable Mutagen (macOS): ddev config --performance-mode=mutagen
2. Increase Docker resources
3. Exclude node_modules from sync if using Mutagen

Database Connection Errors

1. Verify credentials with ddev describe
2. Check the database service: ddev logs -s db
3. Restart the database: ddev restart

Composer Memory Errors

Run Composer with unlimited memory:

ddev exec COMPOSER_MEMORY_LIMIT=-1 composer update

SSL Certificate Warnings

Trust DDEV's certificate authority:

mkcert -install

Conclusion

DDEV takes the pain out of local development. Instead of spending hours configuring environments, you can have a working Craft CMS 5 site running in under five minutes. The consistency it provides means fewer "works on my machine" problems and easier onboarding for new team members.

The tool's flexibility extends beyond just getting started quickly. Whether you're working with Vite for asset compilation, need Redis for caching, or want to match your production environment exactly, DDEV handles it all through simple configuration files that live right in your project.

Our experience shows that teams adopting DDEV report spending significantly less time on environment issues and more time actually building features. The ability to spin up any project with just ddev start changes how teams work, especially when jumping between multiple projects.

Setting up DDEV for your Craft CMS projects requires some initial configuration, but the investment pays off quickly. If you're evaluating local development tools for your team or need help configuring DDEV to match your specific production environment, we can assess your current workflow and recommend the best setup for your needs. We've helped numerous teams migrate from various local development tools to DDEV, ensuring their configurations support both current projects and future growth.