Craft CMS & DDEV: A Quick Start Guide (2022)
![Oscar de la Hera Gomez](https://www.delasign.com/CDN/headshots/profile.webp)
![A flower that represents Craft CMS next to one that represents DDEV. Beneath them sits the text "Craft CMS & DDEV".](https://www.delasign.com/CDN/images/Craft-CMS-DDEV-A-Quick-Start-Guide-2022.webp)
A step by step tutorial on installing DDEV and getting it working with a new or existing Craft CMS project.
With Nitro being retired by Pixel & Tonic, we needed to migrate to DDEV and wanted to share our process.
The following tutorial walks you through the process required to get DDEV installed on your machine. Once we cover that, it also informs you on how to get a new or existing Craft CMS project up and running.
The tutorial was built off the Fortrabbit guide & the Craft CMS official quick start guide which can be found in the link below. Please consult them for any questions that you might have on creating a new project or how DDEV functions compared
Step One: Install Homebrew
![A screenshot of the Homebrew website.](https://www.delasign.com/CDN/images/Install-Homebrew.webp)
We will use Homebrew to install DDEV. Make sure that the Homebrew package manager is installed on your system, using the link below.
Step Two: Install & Open Docker
![A screenshot of Terminal showing you how to run the line written below to install docker.](https://www.delasign.com/CDN/images/Install-Docker.webp)
DDEV works with Docker, which must be both installed and open for the DDEV installation to work.
Install Docker Desktop
brew cask install docker
Open Docker App
open /Applications/Docker.app/
Step Three: Install DDEV
![A screenshot of Terminal showing you the line described below that installs DDEV and the required libraries.](https://www.delasign.com/CDN/images/Install-DDEV.webp)
After making sure that the Docker app is open and has been configured, install DDEV using the following line in terminal.
This will install DDEV and the libraries needed to install it.
brew tap drud/ddev && brew install ddev
Congratulations, you have successfully installed DDEV. The next steps are centered around making DDEV work with an existing Craft CMS project.
If by chance you're looking to start a new project, run the following command line in Terminal in the directory that you wish to create a folder with a new Craft CMS project:
composer create-project craftcms/craft
If you are new to Craft CMS, follow their installation guide provided in the link below.
Step Four: Make the Craft CMS project the current directory
![A screenshot of Terminal showing you how to set the current directory.](https://www.delasign.com/CDN/images/Set-Current-Directory_2022-09-12-174815_kser.webp)
In terminal set the current directory to that of the Craft CMS project that you wish to run with DDEV.
Step Five: Configure DDEV
![A screenshot of Terminal showing you how to configure DDEV to your Craft CMS project. The line is provided below.](https://www.delasign.com/CDN/images/Configure-DDEV.webp)
Run the following command in terminal:
ddev config
Please note that the default docroot is web and the project type is php for Craft CMS. This implies that you can press enter to each question that is asked, as it is the default answer.
Step Six: Update DDEV config.yml
![A screenshot of Visual Studio Code (VSCode) with the DDEV Config.yaml file.](https://www.delasign.com/CDN/images/Update-DDEV-Configyaml.webp)
Under the newly created .ddev folder, modify your config.yaml to your needs. Crafts CMS's suggestions are the following:
- Set
php_version
to whichever you need. (More inconfig.yaml
’s comments.) - The database type can be
mariadb
,mysql
, orpostgres
with a corresponding version. - Use
additional_hostnames
for other*.ddev.site
domain names you’d like to use, oradditional_fqdns
for other custom domain names.
In our case, we updated the settings to take a mysql database to match version 8.0 (highest version allowed by DDEV) and subsequently running the following commands in Terminal:
ddev config --database=mariadb:10.4
Followed by
ddev debug migrate-database mysql:8.0
Step Seven: Start DDEV
![A screenshot of Terminal showing you how to start Craft CMS using DDEV.](https://www.delasign.com/CDN/images/Start-DDEV.webp)
Run the following command in terminal:
ddev start
Step Eight: Run DDEV describe
![A screenshot of Terminal showing you how to get the details of your DDEV instance. The line is provided below.](https://www.delasign.com/CDN/images/DDEV-Describe.webp)
Run the following command in terminal:
ddev describe
Step Nine: Update your .env
![A screenshot that demonstrates the Craft CMS environment variables and the Terminal DDEV describe side by side, along with the changes that were made to ease your understanding. Key elements here are to update all the DB_ parameters.](https://www.delasign.com/CDN/images/Update-Env-Variables.webp)
Update your Craft CMS .env to match the details of the ddev describe.
Step Ten: Add .ddev to gitignore
![A screenshot of the updated gitignore to ignore the .ddev folder.](https://www.delasign.com/CDN/images/Update-Gitignore.webp)
To avoid your project checking in a lot of unnecessary changes, add the .ddev folder to your gitignore.
Step Eleven: Import Database
![A screenshot of Terminal showing you the line that you need to run to import a DB into Craft CMS using DDEV. The line is provided below.](https://www.delasign.com/CDN/images/Import-DB.webp)
Replace YOUR_DB_PATH, with the path of a dump of your existing database and run the following command in terminal:
ddev import-db --src=YOUR_DB_PATH.sql
Step Eleven: Go to your local website
![A screenshot of our Craft CMS running locally through a browser using DDEV.](https://www.delasign.com/CDN/images/Access-your-website.webp)
Copy the Craft CMS website URL found in the ddev describe and paste it into your browser.
Any Questions?
We are actively looking for feedback on how to improve this resource. Please send us a note to inquiries@delasign.com with any thoughts or feedback you may have.