Setting up a development environment

In this section, we will build a development environment using VirtualBox and Vagrant.

Note

Magento official requirements call for Apache 2.2 or 2.4, PHP 5.6.x or 5.5.x (PHP 5.4 is not supported), and MySQL 5.6.x. We need to keep this in mind during the environment setup.

VirtualBox

VirtualBox is powerful and feature-rich x86 and AMD64/Intel64 virtualization software. It is free, runs on a large number of platforms, and supports a large number of guest operating systems. If we are using Windows, Linux, or OS X in our daily development, we can use VirtualBox to spin up a virtual machine with an isolated guest operating system in which we can install our server software needed to run Magento. This means using MySQL, Apache, and a few other things.

Vagrant

Vagrant is a high-level software wrapper used for virtualization software management. We can use it to create and configure development environments. Vagrant supports several types of virtualization software such as VirtualBox, VMware, Kernel-based Virtual Machine (KVM), Linux Containers (LXC), and others. It even supports server environments like Amazon EC2.

Note

Before we start, we need to make sure we have VirtualBox and Vagrant installed already. We can download them and install the following instructions from their official websites: https://www.virtualbox.org and https://www.vagrantup.com.

Vagrant project

We start by manually creating an empty directory somewhere within our host operating system, let's say /Users/branko/www/B05032-Magento-Box/. This is the directory we will pull in Magento code. We want Magento source code to be external to Vagrant box, so we can easily work with it in our favorite IDE.

We then create a Vagrant project directory, let's say /Users/branko/www/magento-box/.

Within the magento-box directory, we run the console command vagrant init. This results in an output as follows:

A 'Vagrantfile' has been placed in this directory. You are now ready to 'vagrant up' your first virtual environment! Please read the comments in the Vagrantfile as well as documentation on 'vagrantup.com' for more information on using Vagrant.

The Vagrantfile is actually a Ruby language source file. If we strip away the comments, its original content looks like the following:

# -*- mode: ruby -*-
# vi: set ft=ruby :

Vagrant.configure(2) do |config|
  config.vm.box = "base"
end

If we were to run vagrant up now within the magento-box directory, this would start the VirtualBox in headless (no GUI) mode and run the base operating system. However, let's hold off running that command just now.

The idea is to create a more robust Vagrantfile that covers everything required for running Magento, from Apache, MySQL, PHP, PHPUnit, composer, and full Magento installation with performance fixture data.

Though Vagrant does not have a separate configuration file on its own, we will create one, as we want to store configuration data like a MySQL user and password in it.

Let's go ahead and create the Vagrantfile.config.yml file, alongside a Vagrantfile in the same directory, with content as follows:

ip: 192.168.10.10
s3:
  access_key: "AKIAIPRNHSWEQNWHLCDQ"
  secret_key: "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"
  bucket: "foggy-project-dhj6"
synced_folder:
  host_path: "/Users/branko/www/B05032-Magento-Box/"
  guest_path: "/vagrant-B05032-Magento-Box/"
mysql:
  host: "127.0.0.1"
  username: root
  password: user123
http_basic:
  repo_magento_com:
    username: a8adc3ac98245f519ua0d2v2c8770ec8
    password: a38488dc908c6d6923754c268vc41bc4
github_oauth:
  github_com: "d79fb920d4m4c2fb9d8798b6ce3a043f0b7c2af6"
magento:
  db_name: "magento"
  admin_firstname: "John"
  admin_lastname: "Doe"
  admin_password: "admin123"
  admin_user: "admin"
  admin_email: "email@change.me"
  backend_frontname: "admin"
  language: "en_US"
  currency: "USD"
  timezone: "Europe/London"
  base_url: "http://magento.box"
  fixture: "small"

There is no Vagrant-imposed structure here. This can be any valid YAML file. The values presented are merely examples of what we can put in.

Magento enables us to generate a pair of 32-character authentication tokens that can use to access the Git repository. This is done by logging in to Magento Connect with a user name and password, then going to My Account | Developers | Secure Keys. The Public Key and Private Key then become our username and password for accessing Magento GitHub repository.

Having a separate configuration file means we can commit Vagrantfile to version control with our project, while leaving the Vagrantfile.config.yml out of version control.

We now edit the Vagrantfile by replacing its content with the following:

# -*- mode: ruby -*-
# vi: set ft=ruby :

require 'yaml'

vagrantConfig = YAML.load_file 'Vagrantfile.config.yml'

Vagrant.configure(2) do |config|

  config.vm.box = "ubuntu/vivid64"

  config.vm.network "private_network", ip: vagrantConfig['ip']

  # Mount local "~/www/B05032-Magento-Box/" path into box's "/vagrant-B05032-Magento-Box/" path
  config.vm.synced_folder vagrantConfig['synced_folder']['host_path'], vagrantConfig['synced_folder']['guest_path'], owner:"vagrant", group: "www-data", mount_options:["dmode=775, fmode=664"]

  # VirtualBox specific settings
  config.vm.provider "virtualbox" do |vb|
    vb.gui = false
    vb.memory = "2048"
    vb.cpus = 2
  end

  # <provisioner here>

end

The preceding code first includes the yaml library, and then reads the content of the Vagrantfile.config.yml file into a vagrantConfig variable. Then we have a config block, within which we define the box type, fixed IP address, shared folder between our host and guest operating system, and a few VirtualBox specific details such as CPU and memory allocated.

We are using the ubuntu/vivid64 box that stands for the server edition of Ubuntu 15.04 (Vivid Vervet). The reason is that this Ubuntu version gives us the MySQL 5.6.x and PHP 5.6.x, which stand as requirements for Magento installation, among other things.

We further have a configuration entry assigning a fixed IP to our virtual machine. Let's go ahead and add an entry in the hosts file of our host operating system as follows:

192.168.10.10 magento.box

Note

The reason why we are assigning the fixed IP address to our box is that we can directly open a URL like http://magento.box within our host operating system, and then access Apache served page within our guest operating system.

Another important part of the preceding code is the one where we defined synced_folder. Besides source and destination paths, the crucial parts here are owner, group, and mount_options. We set those to the vagrant user the www-data user group, and 774 and 664 for directory and file permissions that play nicely with Magento.

Let's continue editing our Vagrantfile adding several provisioners to it, one below the other. We do so by replacing the # <provisioner here> from the preceding example, with content as follows:

config.vm.provision "file", source: "~/.gitconfig", destination: ".gitconfig"
config.vm.provision "shell", inline: "sudo apt-get update"

Here we are instructing Vagrant to pass our .gitconfig file from the host to the guest operating system. This is so we inherit the host operating system Git setup to the guest operating system Git. We then call for apt-get update in order to update the guest operating system.

Provisioning PHP

Further adding to Vagrantfile, we run several provisioners that will install PHP, required PHP modules, and PHPUnit, as follows:

config.vm.provision "shell", inline: "sudo apt-get -y install php5 php5-dev php5-curl php5-imagick php5-gd php5-mcrypt php5-mhash php5-mysql php5-xdebug php5-intl php5-xsl"
config.vm.provision "shell", inline: "sudo php5enmod mcrypt"
config.vm.provision "shell", inline: "echo \"xdebug.max_nesting_level=200\" >> /etc/php5/apache2/php.ini"
config.vm.provision "shell", inline: "sudo apt-get -y install phpunit"

Note

There is one thing worth pointing out here – the line where we are writing xdebug.max_nesting_level=200 into the php.ini file. This is done to exclude the possibility that Magento would not start throwing a Maximum Functions Nesting Level of '100' reached... error.

Provisioning MySQL

Further adding to Vagrantfile, we run provisioners that will install the MySQL server, as follows:

config.vm.provision "shell", inline: "sudo debconf-set-selections <<< 'mysql-server mysql-server/root_password password #{vagrantConfig['mysql']['password']}'"
config.vm.provision "shell", inline: "sudo debconf-set-selections <<< 'mysql-server mysql-server/root_password_again password #{vagrantConfig['mysql']['password']}'"
config.vm.provision "shell", inline: "sudo apt-get -y install mysql-server"
config.vm.provision "shell", inline: "sudo service mysql start"
config.vm.provision "shell", inline: "sudo update-rc.d mysql defaults"

What is interesting with the MySQL installation is that it requires a password and a password confirmation to be provided during installation. This makes it a troubling part of the provisioning process that expects shell commands to simply execute without asking for input. To bypass this, we use debconf-set-selections to store the parameters for input. We read the password from the Vagrantfile.config.yml file and pass it onto debconf-set-selections.

Once installed, update-rc.d mysql defaults will add MySQL to the operating system boot process, thus making sure MySQL is running when we reboot the box.

Provisioning Apache

Further adding to Vagrantfile, we run the Apache provisioner as follows:

config.vm.provision "shell", inline: "sudo apt-get -y install apache2"
config.vm.provision "shell", inline: "sudo update-rc.d apache2 defaults"
config.vm.provision "shell", inline: "sudo service apache2 start"
config.vm.provision "shell", inline: "sudo a2enmod rewrite"
config.vm.provision "shell", inline: "sudo awk '/<Directory \\/>/,/AllowOverride None/{sub(\"None\", \"All\",$0)}{print}' /etc/apache2/apache2.conf > /tmp/tmp.apache2.conf"
config.vm.provision "shell", inline: "sudo mv /tmp/tmp.apache2.conf /etc/apache2/apache2.conf"
config.vm.provision "shell", inline: "sudo awk '/<Directory \\/var\\/www\\/>/,/AllowOverride None/{sub(\"None\", \"All\",$0)}{print}' /etc/apache2/apache2.conf > /tmp/tmp.apache2.conf"
config.vm.provision "shell", inline: "sudo mv /tmp/tmp.apache2.conf /etc/apache2/apache2.conf"
config.vm.provision "shell", inline: "sudo service apache2 stop"

The preceding code installs Apache, adds it to the boot sequence, starts it, and turns on the rewrite module. We then have an update to the Apache configuration file, as we want to replace AllowOverride None with AllowOverride All, or else our Magento won't work. Once the changes are done, we stop Apache due to the later processes.

Provisioning Magento installation

Further adding to Vagrantfile, we now turn our attention to Magento installation, which we split into several steps. First, we link our host folder, /vagrant-B05032-Magento-Box/, with the guest, /var/www/html, using Vagrant's synced folder feature:

config.vm.provision "shell", inline: "sudo rm -Rf /var/www/html"
config.vm.provision "shell", inline: "sudo ln -s #{vagrantConfig['synced_folder']['guest_path']} /var/www/html"

We then use the composer create-project command to pull the Magento 2 files from the official repo.magento.com source into the /var/www/html/ director:

config.vm.provision "shell", inline: "curl -sS https://getcomposer.org/installer | php"
config.vm.provision "shell", inline: "mv composer.phar /usr/local/bin/composer"
config.vm.provision "shell", inline: "composer clearcache"
config.vm.provision "shell", inline: "echo '{\"http-basic\": {\"repo.magento.com\": {\"username\": \"#{vagrantConfig ['http_basic']['repo_magento_com']['username']}\",\"password\": \"#{vagrantConfig['http_basic']['repo_magento_com']['password']} \"}}, \"github-oauth\": {\"github.com\": \"#{vagrantConfig['github_oauth']['github_com']}\"}}' >> /root/.composer/auth.json"
config.vm.provision "shell", inline: "composer create-project -- repository-url=https://repo.magento.com/ magento/project- community-edition /var/www/html/"

We then create a database in which Magento will be installed later on:

config.vm.provision "shell", inline: "sudo mysql -- user=#{vagrantConfig['mysql']['username']} -- password=#{vagrantConfig['mysql']['password']} -e \"CREATE DATABASE #{vagrantConfig['magento']['db_name']};\""

We then run the Magento installation from the command line:

config.vm.provision "shell", inline: "sudo php /var/www/html/bin/magento setup:install --base- url=\"#{vagrantConfig['magento']['base_url']}\" --db- host=\"#{vagrantConfig['mysql']['host']}\" --db- user=\"#{vagrantConfig['mysql']['username']}\" --db- password=\"#{vagrantConfig['mysql']['password']}\" --db- name=\"#{vagrantConfig['magento']['db_name']}\" --admin- firstname=\"#{vagrantConfig['magento']['admin_firstname']}\" -- admin-lastname=\"#{vagrantConfig['magento']['admin_lastname']}\" --admin-email=\"#{vagrantConfig['magento']['admin_email']}\" -- admin-user=\"#{vagrantConfig['magento']['admin_user']}\" -- admin-password=\"#{vagrantConfig['magento']['admin_password']}\" --backend- frontname=\"#{vagrantConfig['magento']['backend_frontname']}\" - -language=\"#{vagrantConfig['magento']['language']}\" -- currency=\"#{vagrantConfig['magento']['currency']}\" -- timezone=\"#{vagrantConfig['magento']['timezone']}\""
config.vm.provision "shell", inline: "sudo php /var/www/html/bin/magento deploy:mode:set developer"
config.vm.provision "shell", inline: "sudo php /var/www/html/bin/magento cache:disable"
config.vm.provision "shell", inline: "sudo php /var/www/html/bin/magento cache:flush"
config.vm.provision "shell", inline: "sudo php /var/www/html/bin/magento setup:performance:generate-fixtures /var/www/html/setup/performance-toolkit/profiles/ce/small.xml"

The preceding code shows we are installing the fixtures data as well.

We need to be careful during the Vagrantfile.config.yml file configuration. Magento installation is quite sensible around provided data. We need to make sure we provide valid data for fields like mail and password or else the installation will fail showing errors similar to the following:

SQLSTATE[28000] [1045] Access denied for user 'root'@'localhost' (using password: NO)
User Name is a required field.
First Name is a required field.
Last Name is a required field.
'magento.box' is not a valid hostname for email address 'john.doe@magento.box'
'magento.box' appears to be a DNS hostname but cannot match TLD against known list
'magento.box' appears to be a local network name but local network names are not allowed
Password is required field.
Your password must be at least 7 characters.
Your password must include both numeric and alphabetic characters.

With this, we conclude our Vagrantfile content.

Running the vagrant up command now within the same directory as Vagrantfile triggers the box creation process. During this process, all of the previously listed commands will get executed. The process alone takes up to an hour or so.

Once vagrant up is complete, we can issue another console command, vagrant ssh, to log in to the box.

At the same time, if we open a URL like http://magento.box in our browser, we should see the Magento storefront loading.

The preceding Vagrantfile simply pulls from the official Magento Git repository and installs Magento from the ground up. Vagrantfile and Vagrantfile.config.yml can be further extended and tailored to suit our individual project needs, like pulling the code from the private Git repository, restoring the database from the shared drive, and so on.

This makes for a simple yet powerful scripting process by which we can prepare fully ready per-project machines for other developers in a team to be able to quickly spin up.