Getting Docker Mount to work in DDev in Craft CMS

Posted on January 04, 2024

Caroline Blaker

Getting Docker Mount to work in DDev in Craft CMS Image

Now you can mount files into your DDev set-up whether Docker can see them or not.

There may be occasions while working websites in DDev - that circumstances would benefit from using files that aren’t in your project already, and without moving them into your project. Why scatter them about, after all, when keeping them where they are would cover more concerns in a streamlined way? However, when you’re using Docker (and DDev relies on Docker,) we see the dark side of containers - that is, the rest of the local development machine doesn’t exist to Docker, and that means your desired other libraries are invisible. Nooo!!

The good news is, you can mount the files you need inside your Docker/ DDev container. Even though the whole project may be contained on the same local machine, Docker’s container-izing of the project adds walls (very containment-like, don’t you think?) which can be an unexpected restriction (no pun intended) of adopting an environment like DDev to handle local code mongering, when other non-Docker solutions don’t make this an issue or have broader reach. The good news is, other local sources of files can be accommodated, from where they already sit. The solution is to mount your secondary library into your primary project, using a docker file in your DDev project directory.


When you’re using DDev, or perhaps as a whole with Docker, your set-up can’t see files outside of the container you’re using. However - you can still work with files that already exist outside your container from within the container, without moving or copying them - by mounting them inside your container.


Big thanks to Lindsey DiLoretto of Double Secret Agency for revealing this as the way in the Craft chat. Apparently this technique is quite common among Craft CMS developers but nobody has decided to write it up - til now. We will be framing this from a Craft CMS developer perspective because that's the one we have.

Let’s go

So, create yourself a new file in the .ddev folder and name it docker-compose.mounts.yaml

Image of Mac OS directory list demonstrating position of file within the .ddev directory

Create docker-compose.mounts.yaml in your project's .ddev directory

My docker-compose.mounts.yaml:

version: '3.6'
 - $HOME/Code/craft-plugins/:/var/www/html/craft-plugins:rw

What this is telling Docker to do is to grab the contents of $HOME/Code/craft-plugins/ and add it to the container, exactly at /var/www/html/craft-plugins and to grant read-write privileges so that changes can be made to the secondary library without needing an additional environment. Your environment may vary, of course, per container or per naming convention. This example is a website container in DDev with an external "craft-plugins" directory. You may need to restart DDev (I use ddev stop ddev start) to apply changes to your environment after saving your content. This won’t affect working website files.

If you do a ddev ssh then a ls -la in the terminal, you ought to have something like the following, if the previous steps worked:

Terminal ls -la showing a craft-plugins directory exactly where we wanted it to be.

We now have craft-plugins included in the directory where it had not been included before. Awesome!

Notice that ddev ssh sent me right to /var/www/html - the path specified in the previous step, and there I can see the craft-plugins directory that I was trying to map in. It worked!

Next, add this clause to your project’s composer.json, using a comma at the end if it's not the very last node:

"repositories": [
 "type": "path",
 "url": "craft-plugins/*",
 "options": {
 "symlink": true
 "type": "composer",
 "url": "",
 "canonical": false

This is telling Composer to look for some software here instead of out there, don’t mind if it’s a symlink, please and thank you. Composer will see this if Docker has indeed mounted the drive inside the container, looking something like the previous image.

Debugging tips

  • Syntax - commas, quotation marks, brackets improperly placed can tank an entire environment. Make sure the file name is character-for-character accurate. I know it’s not fair - I got really, really practiced at undo-redo sequences in code in order to find what went wrong. If you go down the undo-redo rabbit hole, before you do so, be sure to back up your current, broken file so that you don’t lose all your work.
  • First get your files mounted in ddev, then hook them into your project. To check for the success of mounting your files, head over to your terminal with a ddev ssh and then ls -la to see your directory name inserted in the list, and then cd into that place and ls -la to see your files, which are actually elsewhere. Just type exit to get back to your local terminal window any time.
  • Make sure the mounted directory name matches what is added to composer.json, letter-for-letter.
  • Restart DDev whenever you make corrective changes. (I use ddev stop ddev start)

Keep going

Enjoy the ability to develop code for multiple purposes, in various languages, writing features here, bug fixing there. Now that we can include files from outside the container, container-driven solutions don't seem quite so limiting, do they?

comments powered by Disqus