Multi-Site Craft CMS with DDEV

Mul­ti-site local devel­op­ment with Craft CMS and DDEV isn’t chal­leng­ing to man­age. Because Craft han­dles all of the heavy lift­ings of rout­ing the web requests to the cor­rect site in the sys­tem, we only need to set up the prop­er local domains in the DDEV con­fig­u­ra­tion for the project and ensure Craft has those assigned to the respec­tive sites. 

In the Craft CMS project (we’re still work­ing with the Craft Starter Blog project), I have already cre­at­ed three addi­tion­al sites in a site group. The sites are:

1. Microsite One
2. Microsite Two
3. Microsite Three

I also have vari­ables in the .env file for those site URLs: 

And assigned those envi­ron­ment vari­ables to the appro­pri­ate site:

I also cre­at­ed three tem­plate direc­to­ries, one for each site, with an index.twig file in each with the site name variable. 

<h1>{{ siteName }}

This will help us con­firm every­thing is work­ing, once we are ready to test our new mul­ti-site con­fig­u­ra­tion in DDEV.

Con­fig­ur­ing DDEV

This is a typ­i­cal Craft mul­ti-site set­up; it isn’t any­thing spe­cif­ic to how we work with DDEV. How­ev­er, what fol­lows is how we’ll set up DDEV to work with Craft multi-site.

By default, DDEV has one local host­name per project. But in order to set­up mul­ti-site local­ly, we need to cre­ate mul­ti­ple host­names all point­ing at the same DDEV project. 

To do this, we need to jump into the .ddev/config.yaml file, which holds the project-spe­cif­ic con­fig­u­ra­tion for DDEV. This con­fig file is read each time you start or restart the DDEV project. The file is YAML, so for­mat­ting matters. 

Let’s open the .ddev/config.yaml file in our IDE and take a look. 

Around line 9 you should see a key called additional_hostnames with an emp­ty list denot­ed by square brack­ets. This tells us that the val­ue data type is going to be a list. In YAML, that’s a series of hyphens, indent­ed under the key.

The additional_hostnames key is where we will input all of the host­names we need DDEV to cre­ate for this project. This will only be the first part of the domain (something-here.ddev.site), not the entire domain. Keep that in mind while cre­at­ing these on your own. 

We’ll remove the [] and on a new line, add a hyphen­at­ed list of our hostnames:

additional_hostnames:  
  - "microsite-one"  
  - "microsite-two"  
  - "microsite-three"

Since DDEV only reads the con­fig­u­ra­tion file upon start and restart, let’s restart DDEV so it can add the host­names to our project.

ddev restart

And, we see some­thing like this:

Restarted starter-blog
Your project can be reached at https://starter-blog.ddev.site https://microsite-one.ddev.site https://microsite-three.ddev.site https://microsite-two.ddev.site https://127.0.0.1:49696

The project now has the orig­i­nal starter-blog host­name but also three new host­names for our new microsites. Perfect! 

One last thing to do so every­thing works is to add the new domains to our .env file vari­ables for each site. 

SITE_URL="https://starter-blog.ddev.site"  
MICROSITE_ONE="https://microsite-one.ddev.site"  
MICROSITE_TWO="https://microsite-two.ddev.site"  
MICROSITE_THREE="https://microsite-three.ddev.site"

Now, when we access each domain in the brows­er, it should show the cor­rect site!