The DDEV development tool
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.
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:
Basic knowledge of the command line.
PHP and Composer installed on the host machine.
The Homebrew package manager installed.
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!
# 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 tap
brew tap drud/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.
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 ./
# when asked if you are ready to set up craft, answer no, we will do it later
# create DDEV config
# use the suggested defaults by hitting enter
# (<project-name>, 'web', 'php')
# spin up the machine the first time
# this will take a while (once)
# once the machine is running we print out its settings
# 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
# set up Craft from inside the machine
# make sure to use the exact DB credentials as described from inside the container
# 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.
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:
cdto enter your Craft project directory
Once there, run the following commands:
.envfile to reflect the values shown by
Access the URL shown by
ddev describein your browser.
You should be up and running with the Craft site showing in your browser.
You've gotten your local Craft CMS dev site up and running — great! But what's next? Likely, you'll want to deploy your local site to your hosting provider. So le'ts take a look at how to do that. For this example, we use our fortrabbit platform and the Craft Copy tool. With another tool and / or platform the exact specifics will differ. But the general concepts should be similar.
Requirement: have your SSH key set up
Here at fortrabbit, we care deeply about security. Which is why we require our users to connect to our infrastructure using an SSH key. This is contrast to logging in using a username-password combination. To sync your local dev site to fortrabbit, you'll need to:
Have a public-private SSH key pair set up on your local machine.
Have the public key part connected with your fortrabbit Account.
If you're unsure about this, see our help pages for a detailed instruction of how to set up the SSH key.
Deploy a Craft CMS dev site to fortrabbit using Craft Copy
Once the SSH key is set up, we'll configure DDEV to use the keys from your local machine. This will allow us to use Craft Copy from inside the container. Just follow the steps outlined below:
# Make local SSH keys available inside the container
# ( Needs to be done each time you restart your machine )
$ 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 -W
# Update dependencies first
$ composer update
# Install the plugin with Craft CMS
$ php craft plugin/install 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
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. What's even better, DDEV plays nicely with Craft Copy. 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!