Developing With Magento Using An Alpine Docker Cluster
Set up an easy to use local Magento development environment with JetRails’ custom Docker containers. This project allows for an out of the box deployment of any version of Magento utilizing tools like Docker Compose, Docker Sync, and our very own MageRepo.
We built Docker containers that can run any version of Magento. We chose Alpine Linux to be our base image for our containers, because it is lightweight and fast.
Disclaimer: The Docker containers referenced in this article were build for development purposes only and should NOT be used in production. The source code to the Docker containers are licensed under the MIT LICENSE and comes with no warranty. Use at your own risk.
There are some requirements that are needed to run a Docker environment on your local development machine. In order to spin up a Magento development cluster on your local machine, you will need to install Docker and Docker Compose. Additionally, you may want to install Docker Sync if your local machine is not running Linux. For the remainder of this article, we are going to focus on running Docker on macOS.
- Installation instructions for Docker can be found here.
- Installation instructions for Docker Compose can be found here.
- Installation instructions for Docker Sync can be found here.
If you are running Docker on macOS or Windows, then utilizing a tool like Docker Sync is almost a requirement. Docker Sync is an open-source project that can be found on their GitHub repository. Installing Docker Sync will allow us to utilize Docker to it’s full potential. This is extremely important when developing for Magento because Magento alone is heavily reliant on the file system. Docker Sync isn’t as necessary if you are on Linux because Docker volume performance is greater.
Setting up project
When setting up a working environment for your project, consider the following file structure:
$ tree -L 1 . ├── docker-compose.yml ├── docker-sync.yml ├── public_html 1 directories, 2 files
docker-sync.yml file will contain the following:
version: "2" syncs: app-sync: src: "./public_html" sync_userid: 1000 sync_groupid: 1000
We are setting up a volume sync endpoint called
app-sync. We will then reference this endpoint in our
docker-compose.yml file. An example compose file for a Magento 2 deployment looks like the following:
version: "2" volumes: database: app-sync: external: true networks: default: driver: bridge ipam: config: - subnet: "192.168.7.0/28" services: php-fpm: image: jetrails/magento-alpine:php-fpm-7.1 volumes: - app-sync:/var/www/html:rw networks: default: aliases: - php-fpm.docker.internal links: - mysql - redis php-cli: image: jetrails/magento-alpine:php-cli-7.1 volumes: - app-sync:/var/www/html:rw networks: default: aliases: - php-cli.docker.internal links: - mysql - redis php-cron: image: jetrails/magento-alpine:php-cron-7.1 volumes: - app-sync:/var/www/html:rw networks: default: aliases: - php-cron.docker.internal links: - mysql - redis nginx: image: jetrails/magento-alpine:nginx volumes: - app-sync:/var/www/html:rw networks: default: aliases: - nginx.docker.internal environment: - VERBOSE=true - MAGENTO_VERSION=2 links: - php-fpm ports: - "443:443" mysql: image: jetrails/magento-alpine:mysql volumes: - database:/var/lib/mysql networks: default: aliases: - localhost - mysql.docker.internal environment: - MYSQL_ROOT_PASSWORD=magento - MYSQL_USER_NAME=magento - MYSQL_USER_PASSWORD=magento - MYSQL_DATABASE=magento varnish: image: jetrails/magento-alpine:varnish networks: default: aliases: - varnish.docker.internal links: - nginx ports: - "80:80" redis: image: jetrails/magento-alpine:redis networks: default: aliases: - redis.docker.internal
For the remainder of this article, we will assume that the above compose file is used. Whilst the
varnish containers are attached into our cluster, they are not actively caching anything. This needs to be configured separately; we will not go over this process in this article.
Some more sample compose files for running Magento 1 and Magento 2 can be found here.
public_html directory will contain Magento’s source code and is the directory that is used for our
app-sync volume endpoint. For this reason, it is required to exist. We have a CLI tool that can aid in downloading any Magento release. It is discussed in further detail in the Downloading Magento with MageRepo section of this article.
Downloading with MageRepo
MageRepo is a tool built by the JetRails team to make it easier to download and install any version of Magento for development purposes. Any community edition starting from
1.0.0 all the way to the latest can be installed at will. Using our MageRepo Command Line Interface (CLI) Tool makes this even easier. On macOS, this can be installed using Homebrew. For enterprise versions of Magento, there is an authorization process that is required to distribute these releases.
Running the command below will tap our MageRepo repository with brew. After tapping this repository, you can then install formulas that are contained within it.
$ brew tap jetrails/tap $ brew install magerepo
magerepo is extremely simple. Running
magerepo -h from your terminal will output the following help information.
A sample command to download the latest Magento 2 release, extract it into the
public_html folder and then delete the archive looks like this:
$ magerepo release -e ce -r 2.x -c -d -x public_html
More information about the different ways of installing our CLI tool and working with it can be found here. Additional information about working with the MageRepo RESTFUL API can be found in the aforementioned article.
Cluster setup and teardown
Now that everything is good to go, we can start with our deployment process. You can spin up the development cluster using the following sequence of commands.
$ docker-sync start $ docker-compose up -d
Shutting them down is just as easy.
$ docker-compose down $ docker-sync stop $ docker-sync clean # only if not starting again
The whole process (spinning up and then down) will look like the following:
When the cluster is up, you can access the contents of
Attach CLI container on demand
When working with Magento, it is very common to use their
magento CLI binary. A CLI container can be spun up and attached to your cluster by running the following command:
$ docker-compose run php-cli
Once you are done with the shell, you can simply exit it.
Override configuration files
At some point in your development process, you may need to override some files that are baked into our images. If you want to actively change those values while the cluster is up and running, then a new volume endpoint might be the way to go. On the other hand, if you would like to override a single config file, it might be better to just mount it using Docker’s native method. For the sake of example, lets assume you want to override the Varnish config that lives on the
varnish container. Lets also assume that this new config file is located at
conf/default.vcl relative to your project directory. Consider the following modified snippet from the compose file:
varnish: image: jetrails/magento-alpine:varnish volumes: - ./conf/default.vcl:/etc/varnish/default.vcl networks: default: aliases: - varnish.docker.internal links: - nginx ports: - "80:80"
This will override the config file found in
/etc/varnish/default.vcl on the
Supported PHP versions
At the time of writing this article, we support the following PHP versions for
- PHP 5.6
- PHP 7.1
- PHP 7.2
Every Magento release is able to run on one or more of the above listed versions. When authoring your custom composer file, please take into account Magento’s compatibility with the PHP versions listed above.
Our Docker images are publicly published at jetrails/magento-alpine on Docker Hub. Our jetrails/docker-magento-alpine Github repository is also publicly available. We would appropriate any feedback and pull requests that come in. Issues regarding the containers can also be delegated to our Github repository’s issue management system.
Information about customizing the containers using environment variables along with a full list of tags that are published and available for use can be found at the resources stated above.