It is expected that Magento 2 project source code will be located and managed on the host. This is necessary to allow quick indexing of project files by IDE. All other infrastructure is deployed on the guest machine.
Current Vagrant configuration aims to solve performance issues of Magento installed on Virtual Box for development. Custom solution is implemented for Windows hosts. See explanation of the proposed solution.
Environment for Magento EE development is configured as well.
It is easy to install multiple Magento instances based on different codebases simultaneously.
Project initialization script configures complete development environment:
- Adds some missing software on the host
- Configures all software necessary for Magento 2 using custom Ubuntu vagrant box (Apache 2.4, PHP 7.0 (or 5.6), MySQL 5.6, Git, Composer, XDebug, Rabbit MQ, Varnish)
- Installs Magento 2 from Git repositories or Composer packages (can be configured via
checkout_source_fromoption in etc/config.yaml) - Configures PHP Storm project (partially at the moment)
If you never used Vagrant before, read Vagrant Docs
Software listed below should be available in PATH (except for PHP Storm).
-
Git. Make sure you have SSH keys generated and associated with your github account, see how to check and how to configure if not configured.
ℹ️ It is possible to use another way of getting codebase instead of cloning, it does not matter for successful installation. Just put Magento 2 codebase inside ofvagrant-magento/magento2ce.
ℹ️
On Windows hosts Git must be v2.7+, also make sure to set the following options to avoid issues with incorrect line separators:git config --global core.autocrlf false git config --global core.eol LF git config --global diff.renamelimit 5000 -
PHP (any version) to allow Magento dependency management with Composer -
PHP Storm is optional but recommended.
-
NFS server must be installed and running on *nix and OSX hosts. Is usually available, so just try to follow installation steps first.
ℹ️ In case of any issues during installation, please read FAQ section
-
Open terminal and change directory to the one which you want to contain Magento project.
On Windows use Git Bash, which is available after Git installation -
Download project with Vagrant configuration:
git clone [email protected]:paliarush/magento2-vagrant-for-developers.git vagrant-magento
- Optionally, if you use private repositories on GitHub or download packages from Magento Marketplace using Composer
- copy etc/composer/auth.json.dist to
etc/composer/auth.json - specify your GitHub token by adding
"github.com": "your-github-token"togithub-oauthsection for GitHub authorization - add Magento Marketplace keys for Marketplace authorization to
repo.magento.comsection
-
Optionally, copy etc/config.yaml.dist as
etc/config.yamland make necessary customizations -
Initialize project (this will configure environment, install Magento, configure PHPStorm project):
cd vagrant-magento
bash init_project.sh
-
Use
vagrant-magentodirectory as project root in PHP Storm (notvagrant-magento/magento2ce). This is important, because in this case PHP Storm will be configured automatically by init_project.sh. If NFS files sync is disabled in config and on Windows hosts verify deployment configuration in PHP Storm -
Configure remote PHP interpreter in PHP Storm. Go to
Settings => Languages & Frameworks => PHP, add new remote interpreter and select "Deployment configuration" as a source for connection details.
Some of default settings are available for override. These settings can be found in the file etc/config.yaml.dist. To override settings just create a copy of the file under the name 'config.yaml' and put there your custom settings. When using init_project.sh, if not specified manually, random IP address is generated and is used as suffix for host name to prevent collisions, in case when 2 or more instances are running at the same time. Upon a successful installation, you'll see the location and URL of the newly-installed Magento 2 application in console.
Web access:
- Access storefront at
http://magento2.vagrant<random_suffix> - Access admin panel at
http://magento2.vagrant<random_suffix>/admin/ - Magento admin user/password:
admin/123123q - Rabbit MQ control panel:
http://magento2.vagrant<random_suffix>:15672, credentialsguest/guest
Codebase and DB access:
- Path to your Magento installation on the VM:
- Can be retrieved from environment variable:
echo ${MAGENTO_ROOT} - On Windows hosts:
/var/www/magento2ce - On Mac and *nix hosts: the same as on host
- Can be retrieved from environment variable:
- MySQL DB host:
localhost(not accessible remotely) - MySQL DB name:
magento,magento_integration_tests - MySQL DB user/password:
root:<no password>. In CLI just usemysqlwith no user and password (root:<no password>will be used by default)
Codebase on host
- CE codebase:
vagrant_project_root/magento2ce - EE codebase will be available if path to EE repository is specified in
etc/config.yaml:vagrant_project_root/magento2ce/magento2ee
Current vagrant project follows semantic versioning so feel free to pull the latest features and fixes, they will not break your project.
For example your current branch is 2.0, then it will be safe to pull any changes from origin/2.0. However branch 3.0 will contain changes backward incompatible with 2.0.
Note, that semantic versioning is only used for x.0 branches (not for develop).
ℹ️ To apply changes run vagrant reload.
To save some time and get clear Magento installation, you can skip installation of software like web server or php. The following command will clear Magento DB, Magento caches and reinstall Magento instance.
Go to 'vagrant-magento' created earlier and run in command line:
bash m-reinstall
Go to 'vagrant-magento' created earlier and run in command line:
bash m-clear-cache
Assume, that EE codebase is available in vagrant_project_root/magento2ce/magento2ee.
The following commands will link/unlink EE codebase, clear cache, update composer dependencies and reinstall Magento.
Go to 'vagrant-magento' created earlier and run in command line:
bash m-switch-to-ce
OR
bash m-switch-to-ee
Force switch can be done using -f flag even if already switched to the target edition. May be helpful to relink EE modules after switching between branches.
ℹ️ On Windows hosts (or when NFS mode is disabled in config.yaml explicitly) you will be asked to wait until code is uploaded to guest machine by PhpStorm (PhpStorm must be launched). To continue the process press any key.
Make sure that ce_sample_data and ee_sample_data are defined in config.yaml and point CE and optionally EE sample data repositories.
During initial project setup or during bash init_project.sh -fc (with -fc project will be re-created from scratch), sample data repositories willl be checked out to vagrant_project_root/magento2ce/magento2ce-sample-data and vagrant_project_root/magento2ce/magento2ee-sample-data.
To install Magento with sample data set install_sample_data in config.yaml to 1 and run bash m-switch-to-ce -f or bash m-switch-to-ee -f, depending on the edition to be installed. To disable sample data, set this option to 0 and force-switch to necessary edition (using the same commands).
Go to 'vagrant-magento' created earlier and run in command line:
bash m-bin-magento <command_name>
e.g.
bash m-bin-magento list
XDebug is already configured to connect to the host machine automatically. So just:
- Set XDEBUG_SESSION=1 cookie (e.g. using 'easy Xdebug' extension for Firefox). See XDebug documentation for more details
- Start listening for PHP Debug connections in PhpStorm on default 9000 port. See how to integrate XDebug with PhpStorm
- Set beakpoint or set option in PhpStorm menu 'Run -> Break at first line in PHP scripts'
To debug a CLI script:
- Create remote debug configuration in PhpStorm, use
PHPSTORMas IDE key - Run created remote debug configuration
- Run CLI command on the guest as follows (
xdebug.remote_hostvalue might be different for you):
php -d xdebug.remote_autostart=1 <path_to_cli_script>
To debug Magento Setup script, go to Magento installation script and find php ${install_cmd}. Follow steps above for any CLI script
ℹ️ In addition to XDebug support, config.yaml has several options in debug section which allow storefront and admin UI debugging. Plus, desired Magento mode (developer/production/default) can be enabled using magento_mode option, default is developer mode.
Answer can be found here
All emails are saved to 'vagrant-magento/log/email' in HTML format.
It is possible to view/modify majority of guest machine config files directly from IDE on the host. They will be accessible in etc/guest directory only when guest machine is running. The list of accessible configs includes: PHP, Apache, Mysql, Varnish, RabbitMQ. Do not edit any symlinks using PhpStorm because it may break your installation.
After editing configs in IDE it is still required to restart related services manually.
To install several Magento instances based on different code bases, just follow Installation steps to initialize project in another directory on the host.
Unique IP address, SSH port and domain name will be generated for each new instance if not specified manually in etc/config.yaml
Go to 'vagrant-magento' created earlier and run in command line:
bash m-composer install
OR
bash m-composer update
Set "use_php7: 1" for PHP7 and "use_php7: 0" for PHP5.6 in config.yaml. PHP version will be applied after "vagrant reload".
Set use_varnish: 1 to use varnish along apache in config.yaml. Changes will be applied on m-reinstall.
It will use default file etc/magento2_default_varnish.vcl.dist generated from a Magento instance.
Varnish Version: 3.0.5
Use the following commands to enable/disable varnish without reinstalling Magento: m-varnish disable or m-varnish enable.
ℹ️ Available in Magento EE only.
Set search_engine: "elasticsearch" in config.yaml to use ElasticSearch as current search engine or search_engine: "mysql" to use MySQL. Changes will be applied on m-reinstall.
Use the following commands to switch between search engines without reinstalling Magento: m-search-engine elasticsearch or m-search-engine mysql.
ℹ️ Available in Magento v2.0.6 and higher.
Redis is configured as cache backend by default. It is still possible to switch back to filesystem cache by changing environment_cache_backend to filesystem in config.yaml.
It is possible to reset project environment to default state, which you usually get just after project initialization. The following command will delete vagrant box and vagrant project settings. After that it will initialize project from scratch. Magento 2 code base (magento2ce directory) and etc/config.yaml and PhpStorm settings will stay untouched, but guest config files (located in etc/guest) will be cleared.
Go to 'vagrant-magento' created earlier and run in command line:
bash init_project.sh -f
It is possible to reset Magento 2 code base at the same time. Magento 2 code base will be deleted and then cloned from the repositories specified in etc/config.yaml
bash init_project.sh -fc
To reset PhpStorm project configuration, in addition to -f specify -p option:
bash init_project.sh -fp
Ultimate project reset can be achieved by combining all available flags:
bash init_project.sh -fcp
- To debug any CLI script in current Vagrant project, set
debug:vagrant_projectoption in config.yaml to1 - Is Windows 10 supported? Yes, but you may face the same issue as described here. Also Virtual box may not work on Windows 10 in headless mode, see how to enable GUI mode
- On OSX and *nix hosts NFS will be used by default to sync your project files with guest. On some hosts Vagrant cannot configure NFS properly, in this case it is possible to deploy project without NFS by setting
use_nfsoption in config.yaml to0 - On Windows hosts you might face
Composer Install Error: ZipArchive::extractTo(): Full extraction path exceed MAXPATHLEN (260)exception duringcomposer install. This can be fixed in 2 ways: decrease path length to the project directory or setcomposer_prefer_sourceoption in config.yaml to1 - Make sure that you used
vagrant-magentodirectory as project root in PHP Storm (notvagrant-magento/magento2ce) - If project opened in PhpStorm looks broken, close PhpStorm and remove
vagrant-magento/.idea. After opening project in PhpStorm again everything should look good - If code is not synchronized properly on Windows hosts (or when NFS mode is disabled in config.yaml explicitly), make sure that PhpStorm is running before making any changes in the code. This is important because otherwise PhpStorm will not be able to detect changes and upload them to the guest machine
- Please make sure that currently installed software, specified in requirements section, meets minimum version requirement
- If MySQL fails to start and Magento reinstallation fails with
ERROR 2002 (HY000): Can't connect to local MySQL server through socket '/var/run/mysqld/mysqld.sock' (13), try to run login to virtual machine usingvagrant sshand then runsudo dpkg-reconfigure mysql-server-5.6, thensudo service mysql restart. - Be careful if your OS is case-insensitive, NFS might break the symlinks if you cd into the wrong casing and you power the vagrant up. Just be sure to cd in to the casing the directory was originally created as.