Mounting Local Volumes with Docker

One relatively easy way to start developing with Magento is to mount the “app/code”, “app/design”, and “app/i18n” directories on your local host. This allows you to use native text editors on your local environment and protects any work you do from loss – deleting a Docker container will not delete the files in mounted volumes (unlike files hosted locally by the container itself).

The main negatives of this approach is it does not support managing files in directories outside of “app/code”, “app/design”, and “app/i18n”. It also does not support Gulp file watching and does not work with remote AWS nodes. Apart from this however the approach works pretty well with low effort to set up.

To set up the Docker container via Kitematic, click on each of the three volumes and select “Enable Volumes” in the pop-up window. This will bind these three directories inside the Docker container to a directory on your local development machine, allowing you to use a native text editor on your local host.


If you need to create a shell inside the Docker container (say to view other files inside the container), start up a “Docker Quickstart Terminal” and run

docker exec -i -t gsd bash

On Windows at least, I recommend against using the “Docker CLI” button in the bottom left corner of Kitematic (it launches a local shell with environment variables set up correctly to easily run Docker commands). I also recommend against using the “Exec” button above the “container logs” in Kitematic. The reason is these commands both start up a Windows PowerShell prompt (at least at the time when this page was written) which does not correctly support cursor movement escape sequences. This means utilities like “more” and “vi” will not operate correctly. On Windows, “Docker Quickstart Terminal” starts up an “xterm” emulator window, which will support these utilities.

The following screen shot shows connecting to the Docker container and running a Magento CLI command inside the Docker container. (The “magento” Linux account has been created with a password of “magento” if you need to run a command such as “sudo” in this environment.)


In the book series, you will find frequent references to files starting with paths such as “vendor/magento/module-theme”. To view these files, you have several options:

  • You can create a shell inside the Docker container and prefix all paths with “/magento2/”. That is, inside the Docker container above the full path will be “/magento2/vendor/magento/module-theme”.
  • You can make a copy of the source code in the Docker container on your local file system using the following command. (This can be particularly useful when using an IDE such as PHP Storm as it will then have access to all of the source code.)
 docker cp gsd:/magento2 /my/local/directory
  • If the path starts with “app/code”, “app/design”, or “app/i18n” and you have selected “enable volumes”, the files will be on your local host.
  • The code is also available on GitHub, but this approach is not recommended as the “vendor” based paths are a bit different in GitHub, and the code might be a slightly different version. The above approaches are therefore recommended instead.

Because there are multiple ways of setting up your development environment, the book series specifies paths relative to the Magento root directory and leaves it to the reader to work out where these files are actually located in your environment.

For example, if you do not perform the “enable volumes” step, the files under “app/code” are available inside the Docker container. On the other hand, if you enable volumes then this directory will be located both on your host OS (allowing you to use a native text editor) and inside the Docker container. The following screen shot shows a case where the “/magento2/app/code” and “/magento2/app/design” have had “enable volume” selected (and so the files are on the host OS) but “/magento2/app/i18n” has not had “enable volume” selected (for illustration purposes), so the files are inside the Docker container.


If you decide to use this approach of mounting volumes over the other approaches described on other pages, it is generally recommended to always enable all three volumes as if you don’t, the original source code for the “app” directory only exists inside the Docker container. If you delete the container, all files within the container will be lost. If you enable the volumes, the contents of these three directories will be preserved on your local machine even if you delete the container. This is a much safer development approach as long as your changes can be limited to these three directories.

For other related pages, see the “Book” menu at the top right of this page.

%d bloggers like this: