Repository files navigation

⚠️ Current project is not supported anymore. Please check outhttps://github.com/magento/magento2-kubernetes-devbox which is under development and may become an official devbox for Magento 2 in the future.

• What You get
• How to install
  • Requirements
  • Installation steps
  • Default credentials and settings
  • Getting updates and fixes
• Day-to-day development scenarios
  • Reinstall Magento
  • Clear Magento cache
  • Switch between CE and EE
  • Sample data installation
  • Basic data generation
  • Use Magento CLI (bin/magento)
  • Debugging with XDebug
  • Connecting to MySQL DB
  • View emails sent by Magento
  • Accessing PHP and other config files
  • Upgrading Magento
  • Multiple Magento instances
  • Update Composer dependencies
  • Running Magento tests
• Environment configuration
  • Switch between PHP versions
  • Activating Varnish
  • Activating ElasticSearch
  • Redis for caching
  • Reset environment
  • Switch NodeJS Versions
• FAQ

It's expected that the Magento 2 project source code will be located and managed on the host 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 Boxfor development. A custom solution is implemented for Windows hosts. Seeexplanation of the proposed solution.

The environment for Magento EE development is also configured.

It is easy toinstall multiple Magento instances based on different codebases simultaneously.

Theproject initialization script configures a complete development environment:

1. Adds some missing software on the host
2. Configures all software necessary for Magento 2 using acustom Ubuntu vagrant box (Apache 2.4, PHP 7.0 or 5.6, MySQL 5.6, Git, Composer, XDebug, Rabbit MQ, Varnish)
3. Installs Magento 2 from Git repositories or Composer packages (can be configured viacheckout_source_from option inetc/config.yaml)
4. Configures PHP Storm project (partially at the moment)
5. Installs NodeJS, NPM, Grunt and Gulp for front end development

ℹ️ This box uses then package manager to provide the latest NodeJS LTS version.

If you never used Vagrant before, read theVagrant Docs first.

The software listed below should be available inPATH (except for PHP Storm).

• Vagrant 1.8+

• VirtualBox

• Git - Ensure that SSH keys are generated and associated with your Github account. Seehow to check andhow to configure, if not configured.
  ℹ️ To obtain the codebase without cloning, just use the Magento 2 codebase instead ofvagrant-magento/magento2ce. Either method will produce a successful installation.
  

  ℹ️ On Windows hosts Git must bev2.7+. Also make sure to set the following options to avoid issues with incorrect line separators:

  git config --global core.autocrlf falsegit config --global core.eol LFgit config --global diff.renamelimit 5000

• PHP (any version) to allow Magento dependency management withComposer

• PHP Storm, optional but recommended

• NFS server must be installed and running on *nix and OSX hosts; usually available, followinstallation steps first

ℹ️ In case of any issues during installation, please readFAQ section

1. Open terminal and change your directory to the one you want to contain Magento project. On Windows use Git Bash, which is available after Git installation.

2. Download or clone the project with Vagrant configuration:

   ⚠️ Do not open it in PhpStorm untilinit_project.sh has completed PhpStorm configuration in the initialize project step below.

   git clone git@github.com:paliarush/magento2-vagrant-for-developers.git vagrant-magento

   Optionally, if you use private repositories on GitHub or download packages from the Magento Marketplace using Composer

   1. Copyetc/composer/auth.json.dist toetc/composer/auth.json.
   2. Specify your GitHub token by adding"github.com": "your-github-token" to thegithub-oauth section for GitHub authorization.
   3. Add the Magento Marketplace keys for Marketplace authorization to therepo.magento.com section.
   4. Copy (optional)etc/config.yaml.dist asetc/config.yaml and make the necessary customizations.

3. Initialize the project (this will configure the environment, install Magento, and configure the PHPStorm project):

   cd vagrant-magentobash init_project.sh

4. Use thevagrant-magento directory as the project root in PHP Storm (notvagrant-magento/magento2ce). This is important, because in this case PHP Storm will be configured automatically byinit_project.sh. If NFS files sync is disabled inconfig andon Windows hostsverify the deployment configuration in PHP Storm.

   Use the URL for accessing your Magento storefront in the browser as your Web server root URL. Typically this is the localhost, which refers to your development machine. Depending on how you've set up your VM you may also need a port number, likehttp://localhost:8080.

5. Configure the remote PHP interpreter in PHP Storm. Go to Preferences, then Languages and Frameworks. Click PHP and add a new remote interpreter. Select Deployment configuration as a source for connection details.

Some of default settings are available for override. These settings can be found in the fileetc/config.yaml.dist.

To override settings create a copy of the file under the name 'config.yaml' and add your custom settings.

When usinginit_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 two 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 athttp://magento2.vagrant<random_suffix>
• Access admin panel athttp://magento2.vagrant<random_suffix>/admin/
• Magento admin user/password:admin/123123q
• Rabbit MQ control panel:http://magento2.vagrant<random_suffix>:15672, credentialsguest/guest

ℹ️ Your admin URL, storefront URL, and admin user and password are located inetc/config.yaml.dist.

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
• MySQL DB host:localhost (not accessible remotely)
• MySQL DB name:magento,magento_integration_tests
• MySQL DB user/password:root:<no password>. In CLI just usemysql with 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 inetc/config.yaml:vagrant_project_root/magento2ce/magento2ee

Current vagrant project followssemantic versioning so feel free to pull the latest features and fixes, they will not break your project.For example your current branch is2.0, then it will be safe to pull any changes fromorigin/2.0. However branch3.0 will contain changes backward incompatible with2.0.Note, that semantic versioning is only used forx.0 branches (not fordevelop).

ℹ️ To apply changes runvagrant reload.

Use commands described inSwitch between CE and EE section with-f flag. Before doing actual re-installation, these commands update linking of EE codebase, clear cache, update composer dependencies.

If no composer update and relinking of EE codebase is necessary, use the following command. It will clear Magento DB, Magento caches and reinstall Magento instance.

Go to the root of vagrant project in command line and execute:

bash m-reinstall

Go to the root of vagrant project in command line and execute:

bash m-clear-cache

Assume, that EE codebase is available invagrant_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-ceORbash 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.

Upgrade can be performed instead of re-installation using-u flag.

ℹ️ On Windows hosts (or when NFS mode is disabled inconfig.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 thatce_sample_data andee_sample_data are defined inconfig.yaml and point CE and optionally EE sample data repositories.During initial project setup or duringbash init_project.sh -fc (with-fc project will be re-created from scratch), sample data repositories willl be checked out tovagrant_project_root/magento2ce/magento2ce-sample-data andvagrant_project_root/magento2ce/magento2ee-sample-data.

To install Magento with sample data setinstall_sample_data inconfig.yaml to1 and runbash m-switch-to-ce -f orbash m-switch-to-ee -f, depending on the edition to be installed. To disable sample data, set this option to0 and force-switch to necessary edition (using the same commands).

Several entities are generated for testing purposes by default using REST API after Magento installation:

• Customer with address (credentialscustomer@example.com:123123qQ)
• Category
• Couple simple products
• Configurable product

To disable this feature, setmagento/generate_basic_data inconfig.yaml to0 and runbash m-switch-to-ce -f orbash m-switch-to-ee -f, depending on the edition to be installed.

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:

1. Set XDEBUG_SESSION=1 cookie (e.g. using 'easy Xdebug' extension for Firefox). SeeXDebug documentation for more details
2. Start listening for PHP Debug connections in PhpStorm on default 9000 port. See how tointegrate XDebug with PhpStorm
3. Set beakpoint or set option in PhpStorm menu 'Run -> Break at first line in PHP scripts'

To debug a CLI script:

1. Createremote debug configuration in PhpStorm, usephpstorm as IDE key
2. Run created remote debug configuration
3. Run CLI command on the guest as follows (xdebug.remote_host value might be different for you):

php -d xdebug.remote_autostart=1 <path_to_cli_script>

To debug Magento Setup script, go toMagento installation script and findphp ${install_cmd}. Follow steps above for any CLI script

ℹ️ In addition to XDebug support,config.yaml has several options indebug section which allow storefront and admin UI debugging. Plus, desired Magento mode (developer/production/default) can be enabled usingmagento_mode option, default is developer mode.

Answer can be foundhere

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 inetc/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.

Sometimes it is necessary to test upgrade flow. This can be easily done as follows (assuming that you have installed instance):

• For git-based installation - check out codebase corresponding to the target Magento version. Or modify yourcomposer.json in case of composer-based installation
• Use commands described inSwitch between CE and EE section with-u flag

To install several Magento instances based on different code bases, just followInstallation 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 inetc/config.yaml

Go to 'vagrant-magento' created earlier and run in command line:

bash m-composer installORbash m-composer update

Seedraft

Switch between PHP versions using "php_version: " option inconfig.yaml. Supported versions are 5.6, 7.0, 7.1 and 7.2.PHP version will be applied after "vagrant reload".

Setuse_varnish: 1 to use varnish along with apache inconfig.yaml. Changes will be applied onm-reinstall.It will use default file etc/magento2_default_varnish.vcl.dist generated from a Magento 2.1 instance. Magento 2.2+ supports additional Varnish features and you may need to provide custom version of VCL to enable them.Varnish Version: 4.1

Use the following commands to enable/disable varnish without reinstalling Magento:m-varnish disable orm-varnish enable.

ℹ️ Available in Magento EE only.

Setsearch_engine: "elasticsearch" inconfig.yaml to use ElasticSearch as current search engine orsearch_engine: "mysql" to use MySQL. Changes will be applied onm-reinstall.

Use the following commands to switch between search engines without reinstalling Magento:m-search-engine elasticsearch orm-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 changingenvironment_cache_backend tofilesystem inconfig.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) andetc/config.yaml and PhpStorm settings will stay untouched, but guest config files (located inetc/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 inetc/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

By default, the box will install the latestNodeJS LTS version using then package manager. If you need another version ofNode because of Magento'spackage.json requirements, simply run:

n<version>

Note: SeeWorking with npm if after switching versions withn,npm is not working properly.

1. To debug any CLI script in current Vagrant project, setdebug:vagrant_project option inconfig.yaml to1

2. Is Windows 10 supported? Yes, but you may face the same issue as describedhere orhere. Also Virtual box may not work on Windows 10 in headless mode, see how toenable GUI mode

3. 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 settinguse_nfs option inconfig.yaml to0
   

4. On Windows hosts you might faceComposer 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_source option inconfig.yaml to1

5. Make sure that you usedvagrant-magento directory as project root in PHP Storm (notvagrant-magento/magento2ce)

6. If project opened in PhpStorm looks broken, close PhpStorm and removevagrant-magento/.idea. Runbash vagrant-magento/scripts/host/configure_php_storm.sh. After opening project in PhpStorm again everything should look good

7. If code is not synchronized properly on Windows hosts (or when NFS mode is disabled inconfig.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

8. Please make sure that currently installed software, specified inrequirements section, meets minimum version requirement

9. 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.

10. Cannot run unit tests from PHPStorm on Magento 2.2, see possible solutionhere

11. Permission denied (publickey)

12. If during a vagrant reload, the following message appears:

    There was a problem while downloading the metadata for your boxto check for updates. This is not an error, since it is usually dueto temporary network problems. This is just a warning. The problemencountered was:The requested URL returned error: 404 Not Found

    It is likely that your vagrant cli is caching an old url. Perform the following cli commands:

    sed -i --'s/atlas.hashicorp/vagrantcloud/g'~/.vagrant.d/boxes/{name of your paliarush/ubuntu image}/metadata_urlmv~/.vagrant.d/boxes/{name of your paliarush/ubuntu image}/metadata_url2~/.vagrant.d/boxes/{name of your paliarush/ubuntu image}/metadata_url