Docker and Magento

Docker for Magento 2 Illustrative LogoIn this first post, of which many will follow, we show you how to set up Docker for Magento 2 development. Way back when I first heard of Docker, I was still using WAMP, MAMP, Vagrant, VMWare and anything else I could get my hands on. While there are pros and cons to all of the different virtual machine platforms, there was really nothing that truly satisfied all of my needs. It always seemed as though I would get some of the features I needed at the expense of others. Try as I might, I could never quite find the balance I was looking for. When I first started to hear about Docker, I was intrigued yet skeptical, maybe even intimidated.

Crawl Before You Can Walk

I am not, nor have I ever been, a server or dev ops guy. I am a programmer. One day, when I had some free time, I decided to download and install Docker. Despite all that I had read online, I had quite a bit of trouble figuring out how Docker worked and what it's capabilities were. I had read mountains of online documentation and followed countless tutorials. Quite literally, I spent several frustrating weeks, at least 8 hours per day, trying to figure out what I was doing and why it wasn't working. Anyone less stubborn and hard-headed would have abandoned the idea completely. In fact, it's probably the reason I'm going bald. Fortunately, a light bulb did finally pop on above my head and nowadays I am extremely happy with Docker.

Due to the massive frustration I experienced and the sanity that I lost, I just knew I had to make this the first tutorial that I write. My goal is to condense years of experience into a one-page tutorial so that you can get up and running with your Magento 2 projects and keep your hair!

Setup Docker for Magento 2 Development

To follow this tutorial on YouTube, click here.

Install Docker

The first, and perhaps most obvious, step is to download Docker, install it, and start it up. Docker is available for all major operating systems including, but not limited to, Mac OS X, Windows, Ubuntu, Debian, CentOS, and more. The steps in this tut assume that you are on a Mac. However, the steps are the same or very similar no matter what operating system you are on.

Install Composer

Although there are other ways to install and manage Magento 2, Composer is the preferred way. Composer will allow you to manage and install packages as well as allow you to run additional scripts after each update. Additionally, you may have noticed "uninstall" scripts in some Magento extensions. These scripts only work when the extension or module is managed with Composer.

Download Magento 2

To download the Magento 2 Open Source metapackage, do the following:

  1. Log in or create an account on Magento marketplace. Once logged in, navigate to Access Keys and keep that window open as you will need the keys in step #3.
  2. Determine a location on your local machine where you would like the website files to live.
  3. Open up a command line terminal. Before copying and pasting the code below, replace the placeholder path with the absolute path of where you plan to download/install Magento.
    cd /path/to/where/you/will/download/magento && \
    composer create-project --repository-url=https://repo.magento.com/ magento/project-community-edition .
  4. The latest version of Magento 2 is now downloaded to your machine. From this point forward, we will refer to the directory where you installed Magento as /path/to/magento.
  5. Increase the PHP memory limit from the default value of 756M to 2048M.
    find . -name '.htaccess' -exec sed -i '' s/756M/2048M/g {} + && \
    find . -name '.htaccess' -exec sed -i '' s/768M/2048M/g {} + && \
    find . -name '.user.ini' -exec sed -i '' s/756M/2048M/g {} + && \
    find . -name '.user.ini' -exec sed -i '' s/768M/2048M/g {} +
  6. Choose a domain name you would like to use to access the site and add it to your hosts file.
    sudo -- sh -c "echo '127.0.0.1 local.domain.com' >> /etc/hosts"

Create a docker-compose.yml file

  1. Choose a place on your local machine where you will keep your Docker configuration files. We will refer to this location as /path/to/docker.
  2. cd /path/to/docker
  3. Open a new text document in the text editor of your choice.
  4. Copy and past the following code into the new file.
    version: '3'
    services:
        web:
            image: webdevops/php-apache-dev:ubuntu-16.04
            container_name: web
            restart: always
            environment:
              - WEB_ALIAS_DOMAIN=local.domain.com
              - WEB_DOCUMENT_ROOT=/app/pub
              - PHP_DATE_TIMEZONE=EST
              - PHP_DISPLAY_ERRORS=1
              - PHP_MEMORY_LIMIT=2048M
              - PHP_MAX_EXECUTION_TIME=300
              - PHP_POST_MAX_SIZE=500M
              - PHP_UPLOAD_MAX_FILESIZE=1024M
            volumes:
              - /path/to/magento:/app:cached
            ports:
              - "80:80"
              - "443:443"
              - "32823:22"
            links:
              - mysql
        mysql:
            image: mariadb:10
            container_name: mysql
            restart: always
            ports:
              - "3306:3306"
            environment:
              - MYSQL_ROOT_PASSWORD=root
              - MYSQL_DATABASE=magento
            volumes:
              - db-data:/var/lib/mysql
        phpmyadmin:
            container_name: phpmyadmin
            restart: always
            image: phpmyadmin/phpmyadmin:latest
            environment:
              - MYSQL_ROOT_PASSWORD=root
              - PMA_USER=root
              - PMA_PASSWORD=root
            ports:
              - "8080:80"
            links:
              - mysql:db
            depends_on:
              - mysql
    
    volumes:
        db-data:
            external: false
    
  5. Replace the domain name on line 8 with the domain you created earlier in this tutorial.
  6. Replace /path/to/magento on line 17 with the absolute path to the Magento files you downloaded earlier. Leave everything after the colon just the way it is.
  7. Save the new file as /path/to/docker/docker-compose.yml

Now We're Ready to Fire It Up

  1. At this point in time, your terminal should still be open to /path/to/docker.
  2. Fire up your virtual machine! The first time you spin up, Docker needs to download the images, this may take a few minutes. Future spin-ups will only take a few seconds, usually less than 10.
    docker-compose up -d --build
  3. Let's make sure that it's up and running as planned. In a web browser, go to 127.0.0.1:8080 and make sure that you can see phpMyAdmin. If you can, it was a success.

Finally, Let's Install Magento 2!

  1. Access your Docker web container's command line.
    docker exec -it web bash
  2. Navigate to the web document root.
    cd /app
  3. Optional but recommended: deploy sample data.
    php bin/magento sampledata:deploy
  4. Install Magento 2! Before copying and pasting the command shown below into the Docker terminal, you must replace the values on lines 2-6 with your own details. On lines 7-8, replace the placeholder domain with the domain name you created earlier.
    php bin/magento setup:install \
    --admin-firstname=John \
    --admin-lastname=Doe \
    --admin-email=johndoe@example.com \
    --admin-user=admin \
    --admin-password='SomePassword123' \
    --base-url=https://local.domain.com \
    --base-url-secure=https://local.domain.com \
    --backend-frontname=admin \
    --db-host=mysql \
    --db-name=magento \
    --db-user=root \
    --db-password=root \
    --use-rewrites=1 \
    --language=en_US \
    --currency=USD \
    --timezone=America/New_York \
    --use-secure-admin=1 \
    --admin-use-security-key=1 \
    --session-save=files \
    --use-sample-data
  5. In your web browser, visit your website at https://local.domain.com or whatever domain you chose. The first time you go to access the site, it might take a couple of minutes for the page to load. This is because nothing is cached yet and the Magento system is automatically generating files as the page loads. Subsequent page loads will be faster. Additionally, because the web container uses a self-signed SSL certificate, the browser will likely present you with a security alert the first time you visit the URL. Just follow any prompts to add an exception so that you can proceed to the local website.
  6. Congratulations! You are now running Magento 2 on Docker. Keep in mind, this process is easily repeatable for other projects. While you might have spent a bit of time reading through this tutorial, once you have repeated the process a few times, it should only take you 15 minutes or less to spin up a brand new Magento 2 project.

Helpful Docker Information & Commands

Now that you have your Magento 2 project up and running on a series of Docker containers, I would like to share some useful information and commands with you so that you can get the most out of it.

Docker Info

  • Your database is persistent due to a data volume contained in the docker-compose.yml file. This means that when you tear down the virtual machine and spin it back up at a later date or time, your database will still be intact and ready to go.
  • If you would like to use Sequel Pro or some other tool to connect to the database, it is accessible at 127.0.0.1:3306. The username is root and the password is root. The name of the database is magento.
  • The VM includes phpMyAdmin for your convenience. It can be accessed from a web browser at 127.0.0.1:8080.

Docker Commands

  • Spin Up
    docker-compose up -d --build
  • Tear Down
    docker-compose down
  • Connect to web container CLI
    docker exec -it web bash
  • Connect to database container CLI
    docker exec -it mysql bash

About the Docker Image

We want to be sure to give credit where credit is due. On line 4 of the docker-compose.yml file is a reference to the image we use for the web service. That image is: webdevops/php-apache-dev and the docs regarding the image are located here. While I could have assembled my own custom image through the use of a Dockerfile, WebDevOps has gone through the trouble of creating approximately 20 different Docker images that are absolutely perfect for most projects. So a big thank you to WebDevOps for making these images available to the public!

 

Also in the Magento 2 Development Environment Series