Running Magento 2 on Docker

The development environment I have provided for my “Getting Stuff Done with Magento 2” series gets a development environment running locally, including the Luma demo store, with minimal effort.

Simple Installation

This pre-built environment can be installed on Mac or Windows using a technology called “Docker”. When complete, you will have a “Docker container” running Linux, including the Magento 2 source code, an Apache web server, and a MySQL database server. The web server and database server have the Magento 2 Luma demo store pre-loaded.

  1. Install “Docker Toolbox” for Mac or Windows. See for installation instructions. This will install everything you need for Docker based development on your local machine, including Docker Engine, VirtualBox, Kitematic (a GUI for controlling Docker Engine locally), and Docker Quickstart Terminal (an X-terminal emulator for command line access).
  2. Start up “Docker Kitematic”. Do not register a new Docker Hub account or sign in. (If prompted, click the “Skip” button to bypass that step.)
  3. Search for “alankent/gsd” and launch the image by clicking on the “Create” button.
  4. Once the image (~1GB) is downloaded, Kitematic will automatically create a container named “gsd” to run the image in. Do not be concerned if the “web preview” panel shown below is blank. The last line in the log file displayed should have a message about “apache2” running.
  5. Click on the square-and-arrow in the top right corner of the Web Preview panel to launch a web browser. The home page should appear in under 30 seconds of first access. (Subsequent requests will be faster.) To access the Admin panel append “/admin” to the base URL and user username “admin” password “admin123” to log on. (An “Admin” link next to “Sign In” is planned in a future release.)

Your store is now live! If you are not using the store, hover over the “gsd” container near the top left (under the “Containers” heading) and click the cross in a circle to delete the container, reclaiming all resources used (and deleting all changes you made inside the container). The Docker download is cached locally, so to create a new container will not require the 1GB download again (unless a new release of the container is made).

Warning: If you start and stop this container, it will be given different port numbers each time. This can confuse the page cache in Magento causing the cache to hold pages with URLs holding the old port number. To overcome this, use the command line below or go to the “Settings” / “Ports” and type in port numbers for each of the listed ports. E.g. for Docker port 80, change the port number in the MAC IP:PORT column to be 80 (or 8080). This setting is preserved across restarts until the container is deleted.

Command Line Installation

If you are a command line user, you can also achieve the same as the above using the command line. Install Docker Toolbox, as above. Start up “Docker Quickstart Terminal” that was installed alongside Kitematic. Inside this window run the following command.

docker run -d -i -t -p 80:80 -p 3000:3000 -p 3001:3001 -p 2222:22 --name gsd alankent/gsd

This will create a new container like above (it will appear in the Kitematic GUI as well). The extra “-p” command line arguments set up more sensible port number mappings. For example, the web server will be available on port 80 and SSH/SFTP will be available on port 2222 (the Docker Toolbox setup reserves port 22 for its own usage). If you prefer, use -p 8080:80 to have the web server available on port 8080 to avoid port number conflicts. The other two ports (3000 and 30001) are used by BrowserSync, described in volume 2 of my book series for advanced frontend development. If you omit any -p command line options, that port will not be accessible. If you are not using browsersync for example, you can drop “-p 3000:3000 -p 3001:3001”.

To remove the container, use the Kitematic GUI as above or run

docker rm gsd

I personally use a mix of the command line and Kitematic GUI. For example, the GUI makes it easier to start up a web browser without having to work out the URL, but I find the command line quicker than the GUI to set all the port number mappings (I typically create a little shell script or BAT file to start up the container to avoid typing the long command line each time). You can change port number mappings via the GUI (its under settings”/”ports”), but be aware each time you change a setting the container is recreated.

Linux Users

If you run Linux locally with Docker on top, or want to use remote Docker nodes on AWS or similar, you cannot use Kitematic (at least not at the time this page was written). The command line is your only option in such cases.

Inquiring Minds

So how does this all work? As mentioned above, this environment uses a technology called Docker ( Docker allows you to have isolated environments for running code within. If you are familiar with virtualization, you can consider a “Docker container” to be similar to a virtual machine. Magento 1 and Magento 2 for example require different versions of MySQL. By running MySQL in a Docker container you can safely run multiple copies on your local machine without risk of them interfering with each other. It is also easy to share pre-built development environments via a public repository called Docker Hub, which is used here.

There are other technologies that provide similar isolation, such as Vagrant. I had some issues with running Vagrant on Windows, so I settled on using Docker. Vagrant is however probably the more commonly used technology to set up development environments and I may provide Vagrant images to achieve the same purpose in the future.

The following diagram shows the layers of software involved.


At the bottom is your host development machine (typically a Mac or Windows laptop or desktop). On top of this virtualization software (VirtualBox in this case) is used to allow Linux to run on your host machine. (If you run Linux natively you do not need the virtualization software.) Docker Engine then runs inside Linux. A single Docker container is then created holding the combination of Magento source code, web server, and database server.

If you already have Linux, you can consult the official Docker documentation on how to install Docker in such environments. All of the “docker” commands will run in this environment.

In addition, if your local host is too slow or under powered, “Docker Machine” (installed with Docker Toolbox above) allows you to create a AWS or similar cloud server, pre-installed with Docker Engine, making it easy to remotely manage the server. I do not address all possible Docker configurations here – there is a wealth of Docker documentation available for those interested.

The provided development environment consists of a single Docker container to make it easier to start up and shut down the development environment. The goal was for simplicity for developers. Typically with Docker the web server and database server would be run in separate containers.

Next Steps

Now you have a basic understanding of Docker and have the software installed and working, read through the other pages (see the “Book” menu at the top right of this page) on different development environment choices to select the one that suits your needs best.

%d bloggers like this: