Quickly set up a local Craft CMS dev site with the DDEV development tool

Having looked at various dev tools for local PHP development in our previous article on local PHP development, we now focus on Craft CMS development in particular. We'll show you how to use the DDEV development tool to quickly set up a Craft CMS dev site for local development.


The DDEV development tool

A detailed introduction to DDEV was given in our previous article on PHP development tools. Maybe also check out the DDEV website at ddev.com. To quickly sum up:

  • DDEV is a Docker-based tool that targets local PHP development.

  • DDEV supports a number of popular content management systems and frameworks.

  • We can set up DDEV with a standard LAMP stack for local Craft CMS development.

Installation requirements

DDEV sits on top of Docker and works on macOS, Linux, and Windows. The installation will be shown for macOS. To install on Linux you can also use Homebrew on Linux; the steps will be almost identical. The same works for Windows, provided your system has the Windows Subsystem for Linux (WSL) installed.

For this installation procedure, you will need:

  1. Basic knowledge of the command line.

  2. PHP and Composer installed on the host machine.

  3. The Homebrew packet manager installed.

Install DDEV to power your local Craft CMS dev sites

First, we need to install DDEV on our machine.

The first step is to install Docker Desktop. If you already have Docker Desktop installed you can skip this bit. One nice thing is that DDEV tries to accommodate the Docker version already installed on your system. Other dev tools are less well-behaved in that regard.

# install Docker Desktop
brew cask install docker

# make sure to run the Docker App once before proceeding!
open /Applications/Docker.app/
# otherwise the ddev installation will not work

Once we have Docker installed we need to launch the app at least once to complete the configuration. Next, we install DDEV using a custom homebrew “tap”:

# add custom ddev libraries
brew tap drud/ddev && brew install ddev

# install ddev
brew install ddev

If you're using a different operating system, or are uncomfortable using brew, check the official DDEV installation instructions to find alternative means of installing DDEV.

Set up a local Craft CMS dev site with DDEV

In this section we'll show how to set up a brand new Craft CMS site with DDEV for local development. In case you want to use DDEV to power an existing local Craft dev site instead, please refer to our section Using DDEV with an existing Craft CMS installation below.

# create and enter project directory
mkdir craft-ddev && cd ./craft-ddev/

# use Composer to set up a Craft project
composer create-project craftcms/craft ./

# create DDEV config
ddev config
# use the suggested defaults by hitting enter
# (<project-name>, 'web', 'php')

# spin up the machine the first time
ddev start
# this will take a while (once)

# once the machine is running we print out its settings
ddev describe
# note the network and database settings needed for the Craft setup
# this will also show how to connect to your site in the browser after setup

# log in to the running machine to set up Craft
# without this, the database connection will fail
ddev ssh

# set up Craft from inside the machine
# make sure to use the exact DB credentials as described from inside the container
./craft setup
# and leave the machine

That's it. Now you should be able to just access the URL shown via ddev describe in your browser to visit your site.

Using DDEV with an existing Craft CMS installation

We've shown how to use DDEV to set up a fresh dev site for local Craft CMS development. Now you might be curious how to approach your existing local Craft dev sites. Maybe you've been using Homestead or Valet so far, or another PHP development tool. The good news is that it's really easy to use DDEV to host your existing local Craft CMS dev sites as well. Here's how you run an existing Craft site via DDEV:

  1. Use cd to enter your Craft project directory

  2. Once there, run the following commands:

    ddev config

    ddev start

    ddev describe

  3. Edit your .env file to reflect the values shown by ddev describe.

  4. Access the URL shown by ddev describe in your browser.

You should be up and running with the Craft site showing in your browser.


In conclusion, DDEV is a great choice for local Craft CMS development. DDEV can be used to quickly set up a new Craft CMS dev site and works just as well with your existing sites. In case you're already running Docker on your machine, having a local Craft CMS dev site powered by DDEV is just 15 minutes away. We recommend you give DDEV a shot! Easily develop your Craft CMS website locally.

Deploying code to fortrabbit

BONUS: Now, you might want to deploy your local Craft CMS installation to some hosting provider. For this example, we use our fortrabbit platform and the Craft Copy tool but some concepts might be of general interest:


  • Use SSH key auth - not username/password
  • Have some SSH keys installed on your host machine
  • Have your pub key part is connected with your fortrabbit Account

More details on SSH key setup with fortrabbit here: help.fortrabbit.com/ssh-keys

# Copy your local SSH keys to the DDEV machine (from the host)
# ( This might need to be done each time you start the container )
$ ddev auth ssh

# Login to the DDEV container
$ ddev ssh

# Now, in the container, install and setup Craft Copy

# Required to get rid of PHP 7.0 for any Craft CMS lower than 3.6
$ composer config platform --unset

# Include Craft Copy via Composer
$ composer require fortrabbit/craft-copy

# Update dependencies first
$ composer update

# Install the plugin with Craft CMS
$ php craft install/plugin copy

# Initialize the setup
$ php craft copy/setup

# This will guide you through the steps and also run the initial installation.

# Later on you can run the Craft Copy commands:
$ php craft copy/code/up
$ php craft copy/db/up
$ php craft copy/volumes/up

Share & discuss this: